用途：诊断并修复 Capacitor iOS/Android 应用的运行时问题，先定位出错层级（Web、桥接、原生、系统配置），再用对应检查工具验证，最后做最小修复。
触发场景：启动白屏、启动崩溃、原生调用后卡死；“X 插件在 ios/android 未实现”类报错；仅设备端出现的网络失败（net::ERR_CLEARTEXT_NOT_PERMITTED、ATS 需安全连接、CORS）；权限弹窗不出现或总被拒绝；Live Reload 白屏或 Webpage not available；升级到 Capacitor 8.5+/Xcode 27 后 appUrlOpen 静默、通用链接无响应、JS pause/resume 或自定义 AppDelegate 不再执行。
排查流程：先收集平台、模拟器/真机、调试/发布、npx cap doctor 版本、最近改动与完整报错，再按层级分类。JS 异常走 WebView 检查器（Safari 或 chrome://inspect）；插件未实现属桥接注册问题；进程崩溃走 Xcode/Android Studio 调试器。用 npm run build && npx cap sync 后重建原生工程复现，多数“浏览器正常、设备异常”源于素材或插件未同步。iOS 原生控制台可见 ⚡️ 状态信息，Android 看 Capacitor 与 Capacitor/Console 标签。修复前先向用户说明根因与方案，再验证：npx cap doctor 版本一致、npx cap sync 无插件缺失警告、检查器控制台干净，并在模拟器与真机、必要时 release 构建上按原步骤复现确认。
常见修复：插件缺失执行 npm i <plugin> 后 npx cap sync；服务进程拦截请求需在原生构建中停用；仅原生方法在浏览器调用需用 Capacitor.isNativePlatform() / isPluginAvailable 守卫；HTTP 明文仅开发期放开；iOS 缺 NS*UsageDescription 导致权限崩溃需补 Info.plist；Android 权限需补 AndroidManifest 并引导设置；No such module 'Capacitor' 时用 workspace 或重置包缓存。Live Reload：Capacitor 9 用 npx cap run ios --url http://192.168.1.68:5173，8.5 用 npx cap run ios -l --host 192.168.1.68 --port 5173；Android 可用 --forwardPorts 5173:5173，开发服务器需绑定 0.0.0.0，同 Wi-Fi，iOS 可能需本地网络授权。不得将 server.url / server.cleartext 带入发布配置。
限制：不负责日志流式导出与崩溃报告、AppDelegate→SceneDelegate 迁移本身、从零搭建深链、性能调优、生产可观测性、测试编写、设备自动化，以及构建失败、推送、键盘与安全区等其他专用技能覆盖的问题。