debugging-capacitor

调试 Capacitor 应用

找出出问题的层（Web、桥接层、原生层、OS 配置），使用合适的检查器验证判断，然后修复最小范围的问题。

适用场景

在以下情况触发：

• 应用显示白屏或空白屏、启动时崩溃，或在原生调用后冻结。
• 出现错误 "<Name>" plugin is not implemented on ios|android 或 "<Name>.<method>()" is not implemented on ...。
• 仅在设备上网络请求失败：net::ERR_CLEARTEXT_NOT_PERMITTED、ATS "requires the use of a secure connection"、CORS 错误。
• 权限提示从未出现，或总是被拒绝。
• 实时重载（cap run --url、server.url）显示空白页或 "Webpage not available"。
• 更新到 Capacitor 8.5+ / Xcode 27 后：appUrlOpen 无响应，通用链接打开应用后没有任何操作，JS pause/resume 或自定义 AppDelegate 代码不再运行。
• 用户询问“如何调试 / 检查我的 Capacitor 应用”。

请勿用于：

• 只需流式传输、筛选或保存日志或崩溃报告 → ios-android-logs。
• 执行 AppDelegate → SceneDelegate 迁移 → capacitor-uiscene-migration。
• 从头设置深度链接、AASA、assetlinks → capacitor-deep-linking。
• 卡顿、启动缓慢、包体积、内存调优 → capacitor-performance。
• 在生产环境使用 Sentry / Crashlytics / Datadog → capacitor-native-observability。
• 编写单元测试 / E2E 测试 → capacitor-testing。AI/MCP 设备自动化 → capacitor-mcp。
• 版本升级导致的 Gradle/Xcode 构建失败 → capacitor-app-upgrades；Pods/SPM 解析问题 → cocoapods-to-spm。
• 推送令牌 / 投递问题 → capacitor-push-notifications；键盘重叠 → capacitor-keyboard；刘海屏 / 内边距 → safe-area-handling。

排查工作流

1. 先收集事实，再改代码：平台、模拟器还是设备、调试版还是发布版、Capacitor 版本（npx cap doctor）、最近的变更（升级、添加插件、编辑配置）、完整错误文本。
2. 判断出问题的层：
   • JS 异常、请求失败、路由错误 → Web 层：打开 WebView 检查器（Safari / chrome://inspect）。参见 references/webview-inspection.md。
   • plugin is not implemented → 桥接层 / 注册：原生代码未包含在二进制文件中，或无法注入 JS。参见下文“错误处理”。
   • 进程退出 / EXC_BAD_ACCESS / FATAL EXCEPTION → 原生层：在 Xcode / Android Studio 中运行，并附加调试器。参见 references/native-debugging.md。
   • 在 Android 上正常，但在 iOS 上于 8.5/Xcode 27 后出现与链接 / 生命周期相关的问题 → UIScene。参见 references/uiscene-regressions.md。
3. 通过全新同步复现：运行 npm run build && npx cap sync，然后重新构建原生应用。过时的 public/ 资源和未同步的插件，是“在浏览器中正常、在设备上出问题”这类报告的大多数原因。
4. 查看原生控制台中的 Capacitor 自身消息。iOS 会将 ⚡️ Loading app at ...、⚡️ [log] - ...、⚡️ ERROR: Unable to load ... 输出到标准输出（可在 Xcode 控制台、simctl launch --console-pty、devicectl ... launch --console 中查看；Console.app 中看不到）。Android 日志位于标签 Capacitor 下，JS 控制台日志位于 Capacitor/Console 下。日志命令参见 ios-android-logs。
5. 在进行侵入性更改前，先向用户说明根本原因和建议的修复方案（删除 ios/ / android/、编辑 project.pbxproj、全局禁用 ATS）。
6. 应用修复，然后执行“验证”步骤。

工具矩阵

需求	iOS	Android
检查 DOM/JS/网络	Safari > Develop > device > app	chrome://inspect/#devices
原生断点	Xcode（npx cap open ios）、LLDB	Android Studio 调试器（npx cap open android）
从 CLI 在目标设备上运行	npx cap run ios --target <id>	npx cap run android --target <id>
列出目标设备	npx cap run ios --list	npx cap run android --list
打开 URL / 深层链接	xcrun simctl openurl booted <url>；设备：xcrun devicectl device process openURL --device <id> <url>	adb shell am start -W -a android.intent.action.VIEW -d "<url>" <appId>
重置/授予权限（模拟器）	xcrun simctl privacy booted reset all <appId>	adb shell pm revoke <appId> android.permission.CAMERA / adb shell pm clear <appId>
模拟推送（模拟器）	xcrun simctl push booted <appId> payload.json	发送真实的 FCM 消息
启动并输出 stdout	xcrun simctl launch --console-pty booted <appId>；设备：xcrun devicectl device process launch --console --device <id> <appId>	adb logcat
性能分析	Instruments / xcrun xctrace record --template 'Time Profiler'	Android Studio Profiler

详情和注意事项：references/device-cli.md。

Live Reload 快速路径

• Capacitor 9（@next）：npx cap run ios --url http://192.168.1.68:5173。旧版 -l/--live-reload、--host、--port、--https 标志已移除。
• Capacitor 8.5（稳定版）：npx cap run ios -l --host 192.168.1.68 --port 5173（开发服务器使用 https 时添加 --https）。
• Android 模拟器/USB：--forwardPorts 5173:5173 会运行 adb reverse，从而使 http://localhost:5173 可用。
• 开发服务器必须绑定到 0.0.0.0；手机和 Mac 必须连接同一 Wi-Fi；iOS 可能会请求“本地网络”访问权限；如果拒绝，页面将无法加载（可在“设置”>“隐私与安全性”>“本地网络”中重新启用）。
• 绝不要在 capacitor.config.* 中发布 server.url / server.cleartext；发布前请使用 grep 检查。

错误处理

错误 / 症状	可能原因	修复方法
"Foo" plugin is not implemented on ios	插件未添加到原生项目，或 JS 注入被阻止	npm i <plugin> -> npx cap sync ios。SPM：检查 ios/App/CapApp-SPM/Package.swift 是否列出了该插件；CocoaPods：检查 ios/App/Podfile。从 Info.plist 中移除 WKAppBoundDomains，或设置 ios.limitsNavigationsToAppBoundDomains: true。
"Foo" plugin is not implemented on android	Gradle 未同步，或服务工作线程拦截了页面	运行 npx cap sync android，然后选择 File > Sync Project with Gradle Files。在原生构建中禁用或注销服务工作线程。
"Foo.bar()" is not implemented on web	在浏览器中调用仅限原生平台的方法	使用 Capacitor.isNativePlatform() / Capacitor.isPluginAvailable('Foo') 进行判断。
⚡️ ERROR: Unable to load .../index.html / 白屏	webDir 错误或从未复制文件	构建 Web，确认 webDir 与输出文件夹匹配，然后运行 npx cap copy。
白屏，没有原生错误	首次渲染前 JS 崩溃，或 <base href> / 绝对资源路径错误	检查 WebView 控制台；使用可在 capacitor://localhost / https://localhost 下解析的相对路径或根路径。
net::ERR_CLEARTEXT_NOT_PERMITTED	Android 阻止 HTTP（API 28+）	使用 HTTPS。仅用于开发：设置 server.cleartext: true，或使用限定到开发主机的 network_security_config.xml。
"The resource could not be loaded because the App Transport Security policy requires the use of a secure connection."	iOS ATS	使用 HTTPS。仅用于开发：为开发主机设置 NSExceptionDomains，不要全局设置 NSAllowsArbitraryLoads。
仅在设备上出现 API 的 CORS 错误	来源为 capacitor://localhost（iOS）/ https://localhost（Android）	在服务器端允许这些来源，或启用 CapacitorHttp（plugins.CapacitorHttp.enabled: true），以便通过原生方式路由 fetch/XHR。
请求权限时崩溃（iOS，This app has crashed because it attempted to access privacy-sensitive data without a usage description）	缺少 NS*UsageDescription	将该键添加到 ios/App/App/Info.plist。
Android 上权限始终为 denied	缺少 <uses-permission>，或用户两次选择了 "Don't allow"	将其添加到 AndroidManifest.xml；引导用户前往设置。
No such module 'Capacitor'（Xcode）	使用 CocoaPods 时打开了 .xcodeproj，或尚未解析 SPM 软件包	Pods：打开 App.xcworkspace，运行 npx cap sync ios。SPM：选择 File > Packages > Reset Package Caches。更深入的内容 -> cocoapods-to-spm。
Unable to boot device in current state: Booted	模拟器已在运行	这不是错误；使用 booted 作为设备 ID。
仅在 8.5 之后的 iOS 上，appUrlOpen / 通用链接无响应	不再调用 AppDelegate open url / continue userActivity	请参阅 references/uiscene-regressions.md。
JS pause/resume 停止触发	自定义 SceneDelegate 缺少代理转发，或逻辑仍留在 applicationDidEnterBackground 中	请参阅 references/uiscene-regressions.md。

更多针对特定症状的修复方法：references/common-failures.md。

验证

每次修复后都要验证：

1. npx cap doctor 显示匹配的 @capacitor/core、cli、ios、android 版本。
2. npm run build && npx cap sync 执行完成，且没有缺少插件的警告。
3. 原生控制台显示 ⚡️ Loading app at capacitor://localhost...（iOS）/ 没有 Capacitor/Console 错误（Android）。
4. 启动时 WebView 检查器控制台无错误。
5. 在模拟器/模拟器和实体设备上重新运行完全相同的复现步骤；如果该问题仅在发布版本中出现，则使用 release 构建（cap run 默认构建 Debug；iOS 可接受 --configuration Release，Android 发布版本需通过 Android Studio 或 Gradle 构建）。
6. 对于链接/生命周期修复：使用 simctl openurl / adb shell am start 测试冷启动（应用已退出）和热启动（应用在后台），并将应用切换到后台/前台一次，检查 pause 和 resume。
7. 发布前：运行 grep -n "server" capacitor.config.*，确认没有遗留 url/cleartext。

参考资料

仅在涉及相关主题时加载参考资料。

文件	在以下情况下加载
references/webview-inspection.md	附加 Safari/Chrome 检查器、检查器中看不到应用、调试发布版本、启动早期出现 JS 错误
references/native-debugging.md	原生崩溃、在插件中设置断点、LLDB、Android Studio 调试器、Instruments/xctrace、内存泄漏
references/device-cli.md	从终端操作模拟器/设备：安装、启动、打开 URL、权限、推送、应用容器
references/uiscene-regressions.md	iOS 深层链接、通用链接、冷启动 URL、暂停/恢复，或 Capacitor 8.5 / Xcode 27 后损坏的 AppDelegate 代码
references/common-failures.md	白屏、插件未实现、网络、权限、实时重载问题的详细修复方法

资源

• https://capacitorjs.com/docs/ios/troubleshooting
• https://capacitorjs.com/docs/android/troubleshooting
• https://capacitorjs.com/docs/guides/live-reload
• https://capacitorjs.com/docs/updating/8-5
• https://capacitorjs.com/docs/cli/commands/run