capacitor-best-practices

Capacitor 最佳实践

检查 Capacitor 应用是否存在会导致构建失败、编辑内容丢失、生产环境泄漏和插件崩溃的结构性错误。将深入主题交给负责该领域的相关技能。

适用场景

在以下情况触发：

• 用户要求对 Capacitor 或 Ionic + Capacitor 应用进行常规代码／架构审查。
• 设置新的 Capacitor 项目，或为现有 Web 应用添加 iOS／Android 支持。
• 审查 capacitor.config.ts|json：webDir、server.url、cleartext、插件配置、环境特定配置。
• @capacitor/core、@capacitor/cli、@capacitor/ios、@capacitor/android 之间存在版本偏差，或插件主版本与 Capacitor 主版本不匹配。
• 审查插件用法：缺少 npx cap sync、没有可用性检查、没有权限流程、通过错误消息字符串进行判断。
• 出现 "<Plugin>" plugin is not implemented on ios、Could not find the web assets directory、ios platform has not been added yet 等错误。
• 发布前对配置、原生项目和实时更新进行全面检查。

不要用于：

• 安全审计、密钥、存储、证书固定、CSP → capacitor-security；Xcode 加固 → capacitor-ios-security-hardening。
• 包体积、启动时间、内存、Bridge 性能分析 → capacitor-performance。
• 单元／端到端测试设置和插件模拟 → capacitor-testing。
• 崩溃、白屏、原生日志 → debugging-capacitor、ios-android-logs。
• 大版本升级 → capacitor-app-upgrades（8 → 9：capacitor-app-upgrade-v8-to-v9）。
• CocoaPods → SPM → cocoapods-to-spm；采用 UIScene → capacitor-uiscene-migration。
• 查找或安装特定插件 → capacitor-plugins。
• 应用商店提交和审核 → capacitor-app-store、capacitor-apple-review-preflight；CI → capacitor-ci-cd；实时更新 → capgo-live-updates。

当前基线（2026 年 10 月）

	Capacitor 8（稳定版，latest 8.5.x）	Capacitor 9（next，Alpha 版）
Node	22+	24+
iOS 最低版本／Xcode	iOS 15 / Xcode 26（8.5 采用 UIScene，因此可使用 Xcode 27 构建）	iOS 16 / Xcode 27+
Android	minSdk 24，compile/target 36，AGP 8.13，Gradle 8.14.3	minSdk 26，compile/target 37，AGP 9.2.1，Gradle 9.5.1
iOS 依赖项	新项目默认使用 SPM	默认使用 SPM

预计 CocoaPods Trunk 将于 2026 年 12 月 2 日转为只读。对于仍在使用 CocoaPods 的应用，建议改用 SPM。只有在 Capacitor 9 正式发布（GA）前才通过 @next 安装，且不要推荐在生产应用中使用。

审查工作流

1. 盘点（只读）。

   npx cap doctor          # installed vs latest Capacitor packages
   npx cap ls              # plugins Capacitor detects per platform
   cat capacitor.config.ts 2>/dev/null || cat capacitor.config.json
   ls ios/App/Podfile ios/App/CapApp-SPM 2>/dev/null   # CocoaPods or SPM
   grep -nE "minSdkVersion|compileSdkVersion|targetSdkVersion" android/variables.gradle
   

2. 对于大型代码库，列出 TODO 清单，梳理配置、版本、插件、原生 iOS、原生 Android、实时更新和发布等方面，并逐项审查。
3. 编辑前先报告发现的问题，按严重程度分组，并为每项注明文件和行号以及修复方法。进行重大变更前（升级主版本、迁移到 SPM、启用 R8、更改 appId）请先征得同意。
4. 修复，并加载匹配的参考资料。
5. 运行验证。

最重要的规则

1. 确保 Capacitor 软件包使用同一版本。 @capacitor/core、cli、ios、android 必须版本一致。插件的主版本必须与 Capacitor 主版本一致（官方插件和 @capgo/* 插件遵循此规则：Capacitor 8 使用 v8 插件）。
2. 每次安装或移除插件，以及每次更改配置后，都要运行 npx cap sync。 未运行 sync 会导致 "<Plugin>" plugin is not implemented on <platform>。
3. 绝不要编辑生成的 Web 资源。 android/app/src/main/assets/public/ 和 ios/App/App/public/ 会被 cap copy/sync 覆盖。请编辑 src/ 并重新构建。
4. 提交 ios/ 和 android/。 它们是包含原生自定义内容的源代码，不是构建产物。要提交 capacitor.config.*；不要提交 node_modules、Pods/ 或构建目录。
5. 发布配置中不得包含开发设置。 包括 server.url、server.cleartext、指向开发主机的 allowNavigation，以及 webContentsDebuggingEnabled: true。请通过环境变量控制这些设置（参见 references/config-and-project.md）。在 Capacitor 9 中，使用 npx cap run <platform> --url <dev-url> 实现实时重载。
6. 调用插件前先检测功能是否可用。 使用 Capacitor.isNativePlatform()、Capacitor.getPlatform()、Capacitor.isPluginAvailable('Name')。提供 Web 后备方案或隐藏该功能。
7. 使用权限 API。 对于提供权限 API 的官方插件，先调用 checkPermissions()，再调用 requestPermissions()；如果权限被拒绝，应提供前往“设置”的途径。添加相应的 NS*UsageDescription 键和 Android 权限。
8. 根据 error.code 分支处理，而非 error.message。 错误消息会随版本和平台变化。官方插件会提供结构化错误代码（例如，@capacitor/camera 8.1+ 新 API 中，取消拍摄会返回 OS-PLUG-CAMR-0006）；Capacitor core 使用 UNIMPLEMENTED / UNAVAILABLE。
9. 大型二进制数据应以文件形式传输，而非使用 base64。 通过桥接传递文件路径/URI，并使用 Capacitor.convertFileSrc() 渲染。
10. 从 Capacitor 8.5 起，iOS 生命周期基于 scene。 采用 UIScene 后，AppDelegate 的 application(_:open:options:)、continue userActivity 以及前台/后台回调将不再触发。请将自定义原生代码移至 SceneDelegate（capacitor-uiscene-migration）。避免使用 UIScreen.main 和基于设备类型的布局，以适配可调整大小的窗口。
11. 实时更新：每次启动都调用 CapacitorUpdater.notifyAppReady()，手动应用更新时应使用 next()（在进入后台或重新启动时），而不是在会话中途调用 set()。详情见 capgo-live-updates。
12. 绝不要将密钥放入应用中。 Bundle 或 capacitor.config 中的任何内容都可被提取。除此规则之外的任何需求，都应交由 capacitor-security 处理。

参考资料

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

参考资料	何时加载
references/config-and-project.md	检查 capacitor.config、特定环境的构建、仓库布局、.gitignore、版本对齐
references/plugins.md	安装/同步插件、可用性检查、权限、错误代码、Web 后备方案、延迟加载、模拟
references/native-projects.md	iOS SPM 与 CocoaPods、UIScene、部署目标；Android variables.gradle、R8、Capacitor 9 Gradle 变更
references/release-checklist.md	准备发布构建或检查发布就绪情况

验证

# Versions aligned (all @capacitor/* core packages show the same version)
npm ls @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android
npx cap doctor

# Web build exists where webDir points, then sync succeeds without errors
npm run build && npx cap sync

# No dev server or debug flags in the synced native config
grep -nE "\"url\"|cleartext|webContentsDebuggingEnabled" \
  android/app/src/main/assets/capacitor.config.json ios/App/App/capacitor.config.json

# No hand edits in generated web assets (should show nothing)
git status --porcelain android/app/src/main/assets/public ios/App/App/public

# Error handling does not depend on message text
grep -rnE "error\.message\s*(===|==|\.includes)" src/

# Native builds
cd android && ./gradlew assembleRelease && cd ..
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release -destination 'generic/platform=iOS' build CODE_SIGNING_ALLOWED=NO

使用 CocoaPods 时，请通过 -workspace 构建 ios/App/App.xcworkspace，而不是使用 -project。最后，在真机上运行并测试每项由插件支持的功能，包括拒绝权限的情况。

错误处理

错误	原因	修复方法
"<Plugin>" plugin is not implemented on ios（或 android）	已安装插件但未同步，插件没有该平台的实现，或插件主版本与 Capacitor 不匹配	执行 npx cap sync；检查 npx cap ls；安装与 Capacitor 主版本匹配的插件版本；重新构建原生应用
"<Plugin>.<method>()" is not implemented on web	在浏览器中调用仅限原生平台的方法	使用 Capacitor.isNativePlatform() 或 isPluginAvailable 进行判断，并提供 Web 回退方案
Could not find the web assets directory: ./dist.	webDir 设置错误，或 Web 应用尚未构建	先构建；将 webDir 设置为实际输出目录（dist、www、build、out）
ios platform has not been added yet.	缺少原生项目	执行 npx cap add ios（默认使用 SPM），或恢复已提交的 ios/ 文件夹
Invalid App ID "<id>"	appId 不是反向域名格式，或包含无效字符	使用 com.company.app 这类格式；在已发布的应用中更改它会创建新的商店条目
应用在生产环境中加载局域网 IP 或显示空白屏幕	从开发配置中带入了 server.url	删除它，重新构建，执行 npx cap sync，然后重新构建原生应用
net::ERR_CLEARTEXT_NOT_PERMITTED	Android 上的 HTTP 请求	使用 HTTPS；仅在开发配置中使用 cleartext（参见 capacitor-security）
pod install 失败／CocoaPods 规范错误	CocoaPods trunk 弃用、规范过期	使用 cocoapods-to-spm 迁移
8.5 之后，iOS 上的深层链接或 resume 处理停止工作	采用 UIScene 后，自定义代码仍留在 AppDelegate 中	将代码移至 SceneDelegate（capacitor-uiscene-migration）

资源

• Capacitor 文档：https://capacitorjs.com/docs
• 配置参考：https://capacitorjs.com/docs/config
• 特定环境的配置：https://capacitorjs.com/docs/guides/environment-specific-configurations
• 升级到 8.5（UIScene）：https://capacitorjs.com/docs/updating/8-5
• Capgo 文档：https://capgo.app/docs/