capacitor-app-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor App Development

Capacitor 应用开发

General guidance for developing cross-platform apps with Capacitor, covering core concepts, CLI usage, app configuration, platform management, and troubleshooting.

本内容为使用Capacitor开发跨平台应用提供通用指导，涵盖核心概念、CLI使用、应用配置、平台管理及故障排查。

Prerequisites

前提条件

Capacitor 6, 7, or 8 app already created and initialized.
Node.js and npm installed (Node 18+ for Cap 6, Node 20+ for Cap 7, Node 22+ for Cap 8).
For Android: Android Studio installed.
For iOS: Xcode installed on macOS.

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

Agent Behavior

Agent行为规范

Auto-detect before asking. Inspect the project for platforms (
```
android/
```
,
```
ios/
```
), framework (
```
vite.config.ts
```
,
```
angular.json
```
,
```
webpack.config.js
```
,
```
next.config.js
```
), Capacitor version (
```
@capacitor/core
```
in
```
package.json
```
), and iOS dependency manager (
```
ios/App/Podfile
```
for CocoaPods vs. SPM).
Route to the right reference file. Use the topic index below to identify the correct reference file and read it before providing guidance.
One topic at a time. Address the user's specific question. Do not provide a general overview unless explicitly requested.
Prefer actionable instructions. Provide exact file paths, commands, and diff blocks rather than conceptual explanations.

先自动检测再询问：检查项目的平台目录（
```
android/
```
、
```
ios/
```
）、框架配置文件（
```
vite.config.ts
```
、
```
angular.json
```
、
```
webpack.config.js
```
、
```
next.config.js
```
）、Capacitor版本（
```
package.json
```
中的
```
@capacitor/core
```
）以及iOS依赖管理器（通过
```
ios/App/Podfile
```
判断是CocoaPods还是SPM）。
关联正确的参考文件：使用下方的主题索引确定对应的参考文件，查阅后再提供指导。
一次处理一个主题：针对用户的具体问题进行解答，除非明确要求，否则不要提供通用概述。
优先提供可操作的指令：提供精确的文件路径、命令和代码差异块，而非仅概念性解释。

Procedures

操作流程

Step 1: Identify the Topic

步骤1：确定主题

Match the user's request to a topic from the index below. If the request spans multiple topics, address them sequentially.

If the request matches a topic covered by a different skill, redirect the user to that skill (see Related Skills at the bottom).

将用户的请求与下方索引中的主题匹配。如果请求涉及多个主题，按顺序逐一处理。

如果请求属于其他技能覆盖的主题，引导用户使用对应技能（见底部的相关技能）。

Step 2: Analyze the Project

步骤2：分析项目

Auto-detect the following by reading project files:

Capacitor version: Read
```
@capacitor/core
```
version from
```
package.json
```
.
Platforms: Check which directories exist (
```
android/
```
,
```
ios/
```
).
Framework: Check for build tool config files.

Capacitor config format: Check for

capacitor.config.ts

capacitor.config.json

iOS dependency manager: Check for
```
ios/App/Podfile
```
(CocoaPods) or SPM usage.

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

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

Step 3: Read the Reference File and Apply Guidance

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

Read the reference file for the matched topic and apply the instructions to the user's project.

查阅匹配主题对应的参考文件，并将指导内容应用到用户的项目中。

Topic Index

主题索引

Topic	Reference
Core concepts (native bridge, how Capacitor works)	`references/core-concepts.md`
Capacitor platforms (Android, iOS, Electron, PWA)	`references/platforms.md`
Capacitor CLI commands	`references/cli.md`
App configuration ( `capacitor.config.ts` )	`references/app-configuration.md`
Splash screens and app icons	`references/splash-screens-and-icons.md`
Deep links and universal links	`references/deep-links.md`
Android edge-to-edge support	`references/edge-to-edge.md`
Android safe area handling	`references/safe-area.md`
Live reload setup	`references/live-reload.md`
Storage solutions	`references/storage.md`
File handling best practices	`references/file-handling.md`
Security best practices	`references/security.md`
iOS package managers (SPM, CocoaPods)	`references/ios-package-managers.md`
CI/CD for Capacitor apps	`references/ci-cd.md`
Testing (unit and E2E)	`references/testing.md`
Cross-platform best practices	`references/cross-platform-best-practices.md`
Android troubleshooting	`references/troubleshooting-android.md`
iOS troubleshooting	`references/troubleshooting-ios.md`

主题	参考文件
核心概念（原生桥接、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`

Error Handling

故障处理

npx cap sync
fails: Verify
```
@capacitor/core
```
and
```
@capacitor/cli
```
versions match. On iOS with CocoaPods, run
```
cd ios/App && pod install
```
. On Android, sync Gradle files in Android Studio.
Android build fails after configuration changes: Clean the build with
```
cd android && ./gradlew clean
```
, then rebuild.
iOS build fails after configuration changes: Clean the build folder in Xcode (Product > Clean Build Folder) or delete
```
ios/App/Pods
```
and run
```
cd ios/App && pod install
```
.
Plugin not found at runtime: Run
```
npx cap sync
```
after any plugin installation. Verify the plugin appears in
```
capacitor.config
```
or the native project.
Live reload not connecting: Verify the device and development machine are on the same network. Check that the server URL in
```
capacitor.config
```
uses the correct LAN IP address.
Deep links not working: Verify the site association file is accessible at
```
https://<domain>/.well-known/apple-app-site-association
```
(iOS) or
```
https://<domain>/.well-known/assetlinks.json
```
(Android). Verify the app is signed with the correct certificate.

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是否使用了正确的局域网IP地址。
深度链接无法工作：验证站点关联文件是否可通过
```
https://<domain>/.well-known/apple-app-site-association
```
（iOS）或
```
https://<domain>/.well-known/assetlinks.json
```
（Android）访问。验证应用是否使用正确的证书签名。