Capacitor 应用开发与优化最佳实践（项目结构、插件…

在搭建、审查或优化 Capacitor 混合应用时，提供从项目结构、插件使用、性能、安全到上架部署的完整可执行规范。

适用场景

解决思路

1. 项目目录采用 src/（Web 源码）、android/、ios/、capacitor.config.ts、package.json、tsconfig.json 的标准布局。
2. 使用 capacitor.config.ts 而非 capacitor.config.json，并通过 process.env.NODE_ENV === 'development' 条件仅在开发环境启用 server.url 与 cleartext，绝不把开发服务器 URL 提交到生产配置。
3. 保持 Capacitor 核心包版本同步：执行 npm install @capacitor/core@latest @capacitor/cli@latest 与 npm install @capacitor/ios@latest @capacitor/android@latest，然后运行 npx cap sync。
4. 插件安装遵循三步：npm install 插件包 → npx cap sync → iOS 执行 cd ios/App && pod install && cd ../..（或使用 SPM），不可跳过 sync 步骤。
5. 插件使用前先检查可用性：调用 NativeBiometric.isAvailable() 判断 isAvailable 与 biometryType，不可用时回退到密码认证，并用 try/catch 处理用户取消或失败。
6. 对插件使用动态 import 懒加载（如 await import('@capgo/capacitor-document-scanner')），避免在启动时静态导入全部插件导致初始包体积膨胀。
7. 优化 WebView 性能：Android 在 AndroidManifest.xml 的 application 上设置 android:hardwareAccelerated="true" 与 android:largeHeap="true"；iOS 在 Info.plist 中设置 UIViewGroupOpacity 为 false。
8. 减少 JS-native 桥接调用：将多次 Storage.set 合并为一次批量调用，用 JSON.stringify 打包数据。
9. 图片优化：Camera.getPhoto 使用 quality: 80、width: 1024、resultType: CameraResultType.Uri、correctOrientation: true，避免 quality: 100 与 Base64。
10. 敏感数据使用安全存储：用 NativeBiometric.setCredentials / getCredentials 保存凭据，绝不用 Preferences 明文存储密码。
11. 生产环境启用证书固定：在 capacitor.config.ts 中启用 CapacitorHttp，并设置 server.cleartext: false。
12. 使用 @capgo/capacitor-is-root 的 IsRoot.isRooted() 做 Root/越狱检测，检测到后显示安全警告或限制功能。
13. iOS 使用 @capgo/capacitor-app-tracking-transparency 的 AppTrackingTransparency.requestPermission() 请求追踪权限，status === 'authorized' 时才启用分析。
14. 所有插件调用必须做错误处理：区分用户取消（如 'User cancelled photos app' 返回 null）、权限拒绝（弹出权限对话框）与意外错误（记录并抛出）。
15. 使用 Capacitor Updater 做实时更新：调用 CapacitorUpdater.notifyAppReady()，监听 updateAvailable 事件，用 download 后台下载 bundle，再用 set 在下次启动时应用。
16. 更新策略采用后台静默下载、重启时应用（CapacitorUpdater.set），避免在用户使用中调用 CapacitorUpdater.reload() 打断用户。
17. iOS 优先使用 Swift Package Manager（SPM）而非 CocoaPods 管理插件依赖。
18. Android 在 android/app/build.gradle 中配置 minSdkVersion 22、targetSdkVersion 34，release 构建启用 minifyEnabled true 并配置 proguardFiles。
19. 测试时用 jest.mock 模拟插件（如 NativeBiometric 的 isAvailable 与 verifyIdentity），并用 Capacitor.isNativePlatform() 或 Capacitor.getPlatform() 做平台分支。
20. 部署前逐项检查：移除开发服务器 URL、启用 Android ProGuard、设置 iOS 部署目标、真机测试、声明全部权限、弱网测试、深链验证、前后台切换测试、推送通知验证、生物识别边界测试。

适用边界 · 注意事项

• 非 Capacitor 项目或纯 Web 应用不适用。
• 未安装对应 Capacitor 插件或未执行 npx cap sync 时，相关原生能力调用会崩溃。
• 涉及 Capgo 专有插件（如 @capgo/capacitor-updater、@capgo/capacitor-is-root）的部分需依赖 Capgo 生态。