Capacitor 项目需先执行 npx cap add android/ios 注入调试桩，配置 launch.json 使用 capacitor 类型、正确 url 和 webRoot，启用 sourceMap，并手动运行 npx cap sync 同步代码方可调试。
Capacitor 项目在 VSCode 中无法直接调试，核心问题不是插件没装全，而是缺少平台级调试桩和跨 runtime 的断点同步机制——它不像纯 Web 项目那样走 Chrome DevTools，也不像原生 Android/iOS 那样直连 adb 或 lldb。
Capacitor 项目必须先添加目标平台才能调试
Capacitor 是“桥接器”，不是运行时。你写的是 Web 代码，但调试对象是 WebView（Android）或 WKWebView（iOS），所以 npx cap add android 或 npx cap add ios 不只是生成工程文件，更是注入调试代理桩的关键步骤。
- 没执行
npx cap add android就去点“启动调试”，VSCode 会报错No Android project found in android/，因为launch.json里指定的program路径（如android/app/build/outputs/apk/debug/app-debug.apk）根本不存在 - iOS 同理：不运行
npx cap add ios，Xcode 工程没生成，ios/App/App.xcworkspace就是空的，VSCode 找不到可 attach 的进程 - Capacitor 3+ 默认启用
webDir模式，调试时实际加载的是dist/下的构建产物，不是源码目录——所以断点要打在构建后文件上，或确保 Vite/Webpack 开启了sourceMap: true
launch.json 必须用 capacitor 类型而非 chrome 或 cppdbg
VSCode 官方扩展 ms-vscode.cp-debug（2026.1 版）已内置 capacitor 调试类型，它会自动识别 capacitor.config.ts 并启动对应平台的调试代理。用错类型会导致断点灰掉、变量无法读取。
- 正确配置示例：
{ "type": "capacitor", "request": "launch", "name": "Debug on Android", "platform": "android", "url": "http://localhost:3000", "webRoot": "${workspaceFolder}/dist", "sourceMaps": true } -
url必须指向你本地开发服务器地址（如 Vite 的http://localhost:3000），不是file://协议——否则 WebView 拒绝加载，控制台报net::ERR_FILE_NOT_FOUND -
webRoot要和实际构建输出路径一致；若用npm run build输出到www/，就得改成"${workspaceFolder}/www" - 不要手动填
miDebuggerPath或runtimeExecutable——Capacitor 调试不走 GDB/LLDB，那是给原生模块用的
Android 调试需额外开启 USB 调试 + WebView 允许调试
即使 launch.json 正确，真机或模拟器上仍可能看不到源码、断点不触发，常见原因是 WebView 层未授权调试权限。
- 在 Android 设备上打开
开发者选项→ 开启USB 调试，并勾选USB 调试（安全设置） - App 启动后，在 Chrome 地址栏输入
chrome://inspect，检查是否列出你的 Capacitor App；若没出现，进 App 设置里确认是否开启了Web Debugging（部分厂商 ROM 需手动开启） - 在
android/app/src/main/java/.../MainActivity.java中确认有这行：CapacitorWebClient.setAllowNavigation(true);，否则 WebView 会拦截 localhost 请求 - 模拟器建议用 Android Studio 自带的 Pixel 设备（API 33+），避免 Genymotion 等第三方模拟器因 WebView 组件缺失导致调试失败
Capacitor 插件调用调试要切到 native 栈帧
当你在 TypeScript 里调用 await Plugins.Storage.get(...)，断点停在 JS 层是正常的；但想看 Java/Kotlin 或 Swift 实现，必须在调试器里手动切换调用栈到 native 线程。
- Android 下：Chrome
chrome://inspect页面点击 “Configure” → 勾选localhost:9222→ 刷新后点 “inspect”，再在 VSCode 调试面板中右键调用栈 → “Switch to native frame” - iOS 下：需在 Xcode 中先运行
ios/App/App.xcworkspace，让 app 在模拟器启动并保持前台；VSCode 调试器会自动 attach 到WKWebView进程，但 Swift 断点只在 Xcode 里生效，VSCode 仅能观察 JS 层 - 自定义原生插件调试时，
launch.json的platform字段必须与插件实现平台匹配，比如 iOS 插件不能配"platform": "android"，否则调试代理找不到对应符号表
最常被忽略的一点：Capacitor 的 sync 命令不是自动的。每次改完 Web 代码，必须手动运行 npx cap sync（或 npx cap copy）把 dist/ 推送到原生平台目录，否则调试器加载的还是旧版本 HTML/JS。这个步骤没法被 VSCode 任务自动触发，得自己记着。
