capacitor-app-development

Capacitor 应用开发

使用 Capacitor 开发跨平台应用的通用指南，涵盖核心概念、CLI 用法、应用配置、平台管理和故障排查。

前提条件

1. 已创建并初始化 Capacitor 6、7 或 8 应用。
2. 已安装 Node.js 和 npm（Cap 6 需要 Node 18+，Cap 7 需要 Node 20+，Cap 8 需要 Node 22+）。
3. 对于 Android：已安装 Android Studio。
4. 对于 iOS：已在 macOS 上安装 Xcode。

Agent 行为

• 先自动检测，再提问。 检查项目的平台（android/、ios/）、框架（vite.config.ts、angular.json、webpack.config.js、next.config.js）、Capacitor 版本（package.json 中的 @capacitor/core）和 iOS 依赖管理器（检查 ios/App/Podfile，判断使用 CocoaPods 还是 SPM）。
• 选择正确的参考文件。 使用下方的主题索引找到正确的参考文件，并在提供指导前阅读该文件。
• 一次处理一个主题。 针对用户的具体问题进行解答。除非用户明确要求，否则不要提供一般性概述。
• 优先提供可执行的说明。 提供准确的文件路径、命令和差异代码块，而不是概念性解释。

操作步骤

步骤 1：确定主题

将用户的请求与下方索引中的主题对应起来。如果请求涉及多个主题，请依次处理。

如果请求涉及由其他技能涵盖的主题，请将用户引导至该技能（参见底部的“相关技能”）。

步骤 2：分析项目

通过读取项目文件自动检测以下内容：

1. Capacitor 版本：从 package.json 中读取 @capacitor/core 版本。
2. 平台：检查哪些目录存在（android/、ios/）。
3. 框架：检查构建工具配置文件。
4. Capacitor 配置格式：检查是否存在 capacitor.config.ts 或 capacitor.config.json。
5. iOS 依赖管理器：检查是否存在 ios/App/Podfile（CocoaPods）或是否使用 SPM。

步骤 3：阅读参考文件并应用指导

阅读与匹配主题对应的参考文件，并将其中的说明应用到用户的项目中。

主题索引

主题	参考文件
核心概念（原生桥接、Capacitor 的工作原理）	references/core-concepts.md
Capacitor 平台（Android、iOS、Electron、PWA）	references/platforms.md
Capacitor CLI 命令	references/cli.md
应用配置（capacitor.config.ts）	references/app-configuration.md
启动画面和应用图标	references/splash-screens-and-icons.md
深层链接和通用链接	references/deep-links.md
Android 全屏显示支持	references/edge-to-edge.md
Android 安全区域处理	references/safe-area.md
实时重载设置	references/live-reload.md
存储解决方案	references/storage.md
文件处理最佳实践	references/file-handling.md
安全最佳实践	references/security.md
iOS 软件包管理器（SPM、CocoaPods）	references/ios-package-managers.md
Capacitor 应用的 CI/CD	references/ci-cd.md
测试（单元测试和 E2E）	references/testing.md
跨平台最佳实践	references/cross-platform-best-practices.md
Android 故障排查	references/troubleshooting-android.md
iOS 故障排查	references/troubleshooting-ios.md

错误处理

• npx cap sync 失败：确认 @capacitor/core 和 @capacitor/cli 版本一致。在使用 CocoaPods 的 iOS 项目中，运行 cd ios/App && pod install。在 Android 项目中，在 Android Studio 中同步 Gradle 文件。
• 配置更改后 Android 构建失败：运行 cd android && ./gradlew clean 清理构建，然后重新构建。
• 配置更改后 iOS 构建失败：在 Xcode 中清理构建文件夹（Product > Clean Build Folder），或删除 ios/App/Pods 并运行 cd ios/App && pod install。
• 运行时找不到插件：安装任何插件后运行 npx cap sync。确认插件出现在 capacitor.config 或原生项目中。
• 实时重载无法连接：确认设备和开发机器处于同一网络。检查 capacitor.config 中的服务器 URL 是否使用了正确的 LAN IP 地址。
• 深度链接无法使用：确认可通过 https://<domain>/.well-known/apple-app-site-association（iOS）或 https://<domain>/.well-known/assetlinks.json（Android）访问网站关联文件。确认应用使用正确的证书签名。

相关技能

• capacitor-app-creation — 创建新的 Capacitor 应用。
• capacitor-angular — 面向 Angular 的 Capacitor 开发。
• capacitor-react — 面向 React 的 Capacitor 开发。
• capacitor-vue — 面向 Vue 的 Capacitor 开发。
• capacitor-plugins — 安装和配置 Capacitor 插件。
• capacitor-plugin-development — 创建自定义 Capacitor 插件。
• capacitor-app-upgrades — 将 Capacitor 升级到更新的主版本。
• capacitor-in-app-purchases — 设置应用内购买。
• capawesome-cloud — 云构建、实时更新和应用商店发布。
• capacitor-mcp — 将 MCP 客户端连接到当前的 Capacitor 文档。