VSCode调试Capacitor项目必须先执行npx cap add android/ios注入调试桩并生成原生工程，再配置type为capacitor的launch.json、正确url和webRoot，启用sourceMaps，并手动运行npx cap sync同步代码。
VSCode 本身不运行 Capacitor，也不打包 APK 或 IPA；它只负责编辑、启动调试代理、调用命令行工具。真正干活的是 npx cap 命令链、Android Studio 和 Xcode —— VSCode 只是“指挥中心”，配错一步，后续全卡住。
capacitor 调试必须先执行 npx cap add android 或 npx cap add ios
没这步就点“启动调试”，VSCode 会报 No Android project found in android/ 或找不到 ios/App/App.xcworkspace。这不是插件问题，而是 Capacitor 的设计逻辑：它不自带平台工程，add 命令干两件事——生成原生项目结构 + 注入 WebView 调试桩（比如 Android 的 WebView.setWebContentsDebuggingEnabled(true)）。跳过等于没装调试插座，断点再准也传不进 WebView。
- Android 真机调试前，必须在手机上开启“USB 调试”和“WebView 调试”（设置 > 开发者选项 > 启用 WebView 调试）
- iOS 模拟器默认支持调试；真机需在 Xcode 中打开
ios/App/App.xcworkspace，确认 Signing & Capabilities 里已启用 “Automatically manage signing” -
npx cap add android会创建android/目录，但不会自动同步你的前端代码 —— 后续每次改了 HTML/JS，都得手动跑npx cap sync android
launch.json 必须用 "type": "capacitor"，不能用 chrome 或 cppdbg
Capacitor 调试走的是专用代理协议，不是 Chrome DevTools 协议，也不是原生 GDB/LLDB。用错类型会导致断点变灰、this 指向丢失、变量面板空着——看起来像断点没生效，其实是通信通道压根不通。
- 确保安装了最新版
ms-vscode.cp-debug扩展（2026.1+），它才内置capacitor类型 -
url必须是http://localhost:3000这类开发服务器地址，不能是file://—— WebView 会直接拒绝加载，控制台报net::ERR_FILE_NOT_FOUND -
webRoot要严格匹配构建输出路径：Vite 默认是${workspaceFolder}/dist，SvelteKit 可能是${workspaceFolder}/build或${workspaceFolder}/build/client，填错就找不到源码映射 - 别碰
miDebuggerPath或runtimeExecutable—— Capacitor 不需要它们，填了反而干扰
打包 APK / IPA 不在 VSCode 里完成，但关键命令必须在 VSCode 终端中顺序执行
VSCode 终端是唯一可控的入口。顺序错、路径错、环境变量没生效，都会导致 Build APK(s) 在 Android Studio 里失败，或 Xcode 报 Signing certificate not found。
- 先确保终端能识别
adb、java -version、gradle -v；Mac 用户注意 JDK 17 是当前 Android Gradle Plugin 8.4+ 的硬性要求 - 标准流程是：
npx cap sync android→npx cap open android（自动唤起 Android Studio）→ 在 AS 里点Build > Build Bundle(s) / APK(s) > Build APK(s) - 不要手动去
android/app/build/outputs/apk/debug/找文件 —— 如果这个路径不存在，说明sync没成功，或者capacitor.config.ts里webDir指向了错误目录（比如写成"www"但实际构建输出是"dist"） - iOS 打包必须用 Xcode，且首次需手动配置 Team 和 Bundle Identifier；
npx cap open ios打开的是ios/App/App.xcworkspace，不是.xcodeproj
最容易被忽略的其实是 capacitor.config.ts 里的 webDir 和构建命令的耦合关系：Vite 用 npm run build 输出到 dist/，SvelteKit 用 npm run build 可能输出到 build/ 或 build/client/，而 Capacitor 只认 webDir 配置的那一个路径 —— 差一个字符，sync 就静默失败，APK 里还是旧页面。
