capacitor-expert

Capacitor 专家

使用 Capacitor 构建跨平台应用的全面参考。涵盖架构、CLI、插件、框架集成、最佳实践和 Capawesome Cloud。

MCP 服务

有两个托管的 MCP 服务提供最新文档，因此它们始终比此技能随附的指南更新：

• Capawesome MCP 服务 —— Capawesome 插件、Capawesome CLI 和 Capawesome Cloud。
• Capacitor MCP 服务（非官方）—— Capacitor 本身：CLI、capacitor.config 文件、原生 Android 和 iOS 项目，以及官方插件 API。

两者都提供 search_docs 和 get_doc_page，因此调用前应根据主题选择服务。

• 如果 MCP 工具可用，请在负责该主题的服务上调用 search_docs，并使用 get_doc_page 阅读匹配页面，然后再应用以下指南。如果两者内容不一致，请以文档为准。
• 如果 MCP 工具不可用，请提及一次可使用以下命令添加这些服务，然后继续使用此技能。切勿因此中断。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp"

查阅文档无需任何服务的账户或令牌。完整设置说明（包括 Capawesome Cloud 工具）请参阅 capawesome-mcp 和 capacitor-mcp 技能。

核心概念

Capacitor 是一个跨平台原生运行时，可用于构建能够在 iOS、Android 和 Web 上原生运行的 Web 应用。Web 应用运行在原生 WebView 中，Capacitor 则通过插件提供原生 API 桥接。

架构

Capacitor 应用包含三个层：

1. Web 层——在原生 WebView 中运行的 HTML/CSS/JS 应用（iOS 上为 WKWebView，Android 上为 Android System WebView）。
2. 原生桥接层——序列化 JS 插件调用，将其路由到原生代码，并以 Promise 的形式返回结果。
3. 原生层——实现原生功能的 Swift/ObjC（iOS）和 Kotlin/Java（Android）代码。

通过桥接传递的数据必须可序列化为 JSON。传递文件时应使用路径，而非 base64。

项目结构

my-app/
  android/                  # Native Android project (committed to VCS)
  ios/                      # Native iOS project (committed to VCS)
    App/
      App/                  # iOS app source files
      App.xcodeproj/
  src/                      # Web app source code
  dist/ or www/ or build/   # Built web assets
  capacitor.config.ts       # Capacitor configuration
  package.json

android/ 和 ios/ 目录是完整的原生项目——应纳入版本控制，也可以直接修改。

Capacitor 配置

capacitor.config.ts（首选）或 capacitor.config.json 用于控制应用行为：

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  server: {
    // androidScheme: 'https', // default in Cap 6+
  },
};

export default config;

详情请参阅应用配置。

创建新应用

快速开始

# 1. Create a web app (React example with Vite)
npm create vite@latest my-app -- --template react-ts
cd my-app && npm install

# 2. Install Capacitor
npm install @capacitor/core
npm install -D @capacitor/cli

# 3. Initialize Capacitor
npx cap init "My App" com.example.myapp --web-dir dist

# 4. Build web assets
npm run build

# 5. Add platforms
npm install @capacitor/android @capacitor/ios
npx cap add android
npx cap add ios

# 6. Sync and run
npx cap sync
npx cap run android
npx cap run ios

各框架的 Web 资源目录：

• Angular：dist/<project-name>/browser（Angular 17+，使用 application builder）
• React（Vite）：dist
• Vue（Vite）：dist
• Vanilla：www

完整的分步创建流程请参阅 capacitor-app-creation。

Capacitor CLI

所有命令格式均为 npx cap <command>。最重要的命令：

命令	用途
npx cap init <name> <id>	在项目中初始化 Capacitor
npx cap add <platform>	添加 Android 或 iOS 平台
npx cap sync	复制 Web 资源并更新原生依赖（每次安装插件、更改配置或构建 Web 应用后运行）
npx cap copy	仅复制 Web 资源（速度更快，不更新原生依赖）
npx cap run <platform>	构建、同步并部署到设备/模拟器
npx cap run <platform> -l --external	使用实时重载运行
npx cap open <platform>	在 IDE 中打开原生项目
npx cap build <platform>	构建原生项目
npx cap doctor	诊断配置问题
npx cap ls	列出已安装的插件

完整 CLI 参考请参阅 CLI 参考。

框架集成

Capacitor 适用于任何 Web 框架。各框架的特定模式：

Angular

• 将 Capacitor 插件封装在 Angular 服务中，以便进行依赖注入并提高可测试性。
• 插件事件监听器在 NgZone 外运行——始终使用 NgZone.run() 封装回调。
• 在 ngOnInit 中注册监听器，并在 ngOnDestroy 中移除。

详情请参阅 capacitor-angular。

React

• 创建自定义 Hook（useCamera、useNetwork）来封装 Capacitor 插件。
• 使用 useEffect 注册监听器并进行清理，以防止内存泄漏。
• React 18 严格模式会执行两次挂载——请确保清理函数能正常工作。

详情请参阅 capacitor-react。

Vue

• 使用 Vue 3 Composition API 创建组合式函数（useCamera、useNetwork）。
• 在 onMounted 中注册监听器，并在 onUnmounted 中移除。
• Vue 响应式系统会自动检测 ref 变化（无需类似 NgZone 的机制）。

详情请参阅 capacitor-vue。

插件

插件是 Capacitor 的扩展机制。每个插件都提供由原生实现支持的 JS API。

插件来源

• 官方（@capacitor/*）——Camera、Filesystem、Geolocation、Preferences 等。
• Capawesome（@capawesome/*、@capawesome-team/*）——SQLite、NFC、Biometrics、Live Update 等。
• 社区（@capacitor-community/*）——AdMob、BLE、SQLite、Stripe 等。
• Firebase（@capacitor-firebase/*）——Analytics、Auth、Messaging、Firestore 等。
• MLKit（@capacitor-mlkit/*）——条码扫描、人脸检测、翻译。
• RevenueCat（@revenuecat/purchases-capacitor）——应用内购买。

安装插件

npm install @capacitor/camera
npx cap sync

安装后，请按照插件文档应用所需的平台配置（例如，AndroidManifest.xml 中的权限、Info.plist 条目等）。

使用插件

import { Camera, CameraResultType } from '@capacitor/camera';

const photo = await Camera.getPhoto({
  quality: 90,
  resultType: CameraResultType.Uri,
});

完整的插件索引（160 多个插件）和设置指南，请参阅 capacitor-plugins。

插件开发

使用 iOS（Swift）和 Android（Java/Kotlin）原生实现创建自定义 Capacitor 插件：

1. 使用 npm init @capacitor/plugin@latest 搭建项目。
2. 在 src/definitions.ts 中定义 TypeScript API。
3. 在 src/web.ts 中实现 Web 层。
4. 在 ios/Sources/ 中实现 iOS 插件。
5. 在 android/src/main/java/ 中实现 Android 插件。
6. 使用 npm run verify 验证。

关键规则：

• src/index.ts 中的 registerPlugin() 名称必须与 iOS 上的 jsName 以及 Android 上的 @CapacitorPlugin(name = "...") 匹配。
• iOS 方法需要使用 @objc，并且必须列在 pluginMethods 中（CAPBridgedPlugin）。
• Android 方法需要使用 @PluginMethod() 注解，并且必须为 public。

完整详情请参阅 capacitor-plugin-development。

跨平台最佳实践

平台检测

import { Capacitor } from '@capacitor/core';

const platform = Capacitor.getPlatform(); // 'android' | 'ios' | 'web'
if (Capacitor.isNativePlatform()) { /* native-only code */ }
if (Capacitor.isPluginAvailable('Camera')) { /* plugin available */ }

权限

遵循先检查、再请求的模式：

const status = await Camera.checkPermissions();
if (status.camera !== 'granted') {
  const requested = await Camera.requestPermissions();
  if (requested.camera === 'denied') {
    // Guide user to app settings -- cannot re-request on iOS
    return;
  }
}
const photo = await Camera.getPhoto({ ... });

性能

• 尽量减少桥接调用——将操作批量处理，而不是进行多次单独调用。
• 二进制数据优先使用文件路径，而不是 base64。
• 使用动态导入延迟加载插件，以拆分代码。

错误处理

始终使用 try-catch 包装插件调用：

try {
  const photo = await Camera.getPhoto({ resultType: CameraResultType.Uri });
} catch (error) {
  if (error.message === 'User cancelled photos app') {
    // Not an error
  } else {
    console.error('Camera error:', error);
  }
}

完整详情请参阅 跨平台最佳实践。

深层链接

深层链接可通过外部 URL 在应用中打开特定内容。

• iOS：通过托管在 https://<domain>/.well-known/ 的 apple-app-site-association 配置通用链接。
• Android：通过托管在 https://<domain>/.well-known/ 的 assetlinks.json 配置应用链接。

监听器设置

import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  const path = new URL(event.url).pathname;
  // Route to the appropriate page
});

平台配置

• iOS：在 ios/App/App/App.entitlements 的 Associated Domains 功能中添加 applinks:<domain>。
• Android：在 android/app/src/main/AndroidManifest.xml 中添加 <intent-filter android:autoVerify="true">。

完整设置说明请参阅 深度链接。

存储

要求	解决方案
应用设置、偏好设置	@capacitor/preferences（原生键值存储，可靠持久化）
敏感数据（令牌、凭据）	@capawesome-team/capacitor-secure-preferences（Keychain/Keystore）
关系型数据、离线优先	SQLite（@capawesome-team/capacitor-sqlite 或 @capacitor-community/sqlite）
文件、图像、文档	@capacitor/filesystem

不要使用 localStorage、IndexedDB 或 Cookie 存储持久化数据——操作系统可能会清除这些数据（尤其是在 iOS 上）。

详情请参阅 存储。

安全

• 切勿在客户端代码中嵌入密钥（具有写入权限的 API 密钥、OAuth 密钥、数据库凭据）——应将其移至服务端 API。
• 使用安全存储（@capawesome-team/capacitor-secure-preferences）存储令牌和凭据，不要使用 localStorage 或 @capacitor/preferences。
• 仅使用 HTTPS——生产环境中切勿允许明文 HTTP。
• 内容安全策略——在 index.html 中添加 <meta> CSP 标签。
• 在生产环境中禁用 WebView 调试：在 capacitor.config.ts 中将 webContentsDebuggingEnabled: false。
• 优先使用 Universal/App Links，而非自定义 URL 方案（通过 HTTPS 验证）。
• iOS 隐私清单（PrivacyInfo.xcprivacy）——在 iOS 17+ 上使用隐私敏感 API 时必须提供。

详情请参阅 安全。

测试

单元测试

由于测试在 Node.js 中运行，而非 WebView 中，因此请在 Jest/Vitest 中模拟 Capacitor 插件：

vi.mock('@capacitor/camera', () => ({
  Camera: {
    getPhoto: vi.fn().mockResolvedValue({
      webPath: 'https://example.com/photo.jpg',
    }),
  },
}));

端到端测试

• Web 端到端测试：Cypress 或 Playwright（测试 Web 层，必须模拟插件）。
• 原生端到端测试：Appium（跨平台）或 Detox（侧重 iOS）。

调试

• Android：启用 webContentsDebuggingEnabled: true，在 Chrome 中打开 chrome://inspect。
• iOS：启用 webContentsDebuggingEnabled: true，使用 Safari > Develop 菜单 > 选择设备。

详情请参阅 测试。

故障排除

Android

• npx cap sync 失败：确认 @capacitor/core 和 @capacitor/cli 版本一致。运行 cd android && ./gradlew clean。
• 配置更改后构建失败：运行 cd android && ./gradlew clean 清理，然后重新构建。
• 运行时找不到插件：安装插件后运行 npx cap sync。确认 Gradle 同步已完成。
• SDK 错误：确认已设置 ANDROID_HOME。通过 Android Studio SDK Manager 安装缺失的 SDK 版本。
• 通知图标显示为白色方块：推送通知图标必须是透明背景上的白色像素。

iOS

• 构建失败并提示 “no such module”：运行 npx cap sync ios。对于 CocoaPods：运行 cd ios/App && pod install --repo-update。
• 配置更改后构建失败：清理构建文件夹（Xcode Product > Clean Build Folder），或删除 ios/App/Pods 并重新运行 pod install。
• 模拟器无法接收推送通知：使用实体设备测试推送通知。
• 权限被永久拒绝：iOS 不允许重新请求权限。请引导用户前往 Settings > App > Permissions。
• WebView 无法加载：确认 capacitor.config.ts 中的 webDir 与实际构建输出目录一致。

常见问题

• 实时重载无法连接：确保设备和开发机器位于同一网络。使用 --external 标志。
• 未找到插件：运行 npx cap sync。确认 package.json 依赖项中包含该插件。
• Capacitor is not defined：安装 @capacitor/core（npm install @capacitor/core）。

如需完整的故障排除指南，请参阅 Android 故障排除和 iOS 故障排除。

升级

Capacitor 支持跨主版本升级（4 到 8）。每次主版本升级都必须按顺序进行，不要跳过中间版本。

当前版本到目标版本	Node.js	Xcode	Android Studio
升级到 5	16+	14.1+	Flamingo 2022.2.1+
升级到 6	18+	15.0+	Hedgehog 2023.1.1+
升级到 7	20+	16.0+	Ladybug 2024.2.1+
升级到 8	22+	26.0+	Otter 2025.2.1+

不要运行 npx cap migrate。这是一个交互式命令，无法由 Agent 调用。请使用各版本的参考文件手动应用所有升级步骤。

应用升级请参阅 capacitor-app-upgrades。 插件升级请参阅 capacitor-plugin-upgrades。

Capawesome Cloud

Capawesome Cloud 为 Capacitor 应用提供云基础设施：原生构建、实时更新和自动化应用商店发布。

网站：capawesome.io | 云服务：capawesome.io/cloud/

快速入门

# Install and authenticate
npx @capawesome/cli login

# Create an app
npx @capawesome/cli apps:create

实时更新

通过空中下载（OTA）方式向 Capacitor 应用部署 Web 更新，无需经过应用商店。用户会在下次启动应用时立即收到更新。

设置：

# Install the live update plugin
npm install @capawesome/capacitor-live-update
npx cap sync

在 capacitor.config.ts 中配置：

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: '<APP_ID>',
      autoUpdate: true,
    },
  },
};

部署更新：

npm run build
npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID>

原生构建

无需本地构建环境，即可在云端构建 iOS 和 Android 应用。支持签名证书、环境和构建配置。

# Trigger a build
npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform android

# Download the artifact
npx @capawesome/cli apps:builds:download --app-id <APP_ID> --build-id <BUILD_ID>

应用商店发布

自动向 Apple App Store（TestFlight）和 Google Play Store 提交应用。

# Create a deployment destination
npx @capawesome/cli apps:destinations:create --app-id <APP_ID>

# Deploy a build
npx @capawesome/cli apps:deployments:create --app-id <APP_ID> --build-id <BUILD_ID>

CI/CD 集成

在 CI/CD 流水线中使用基于令牌的身份验证：

npx @capawesome/cli login --token <TOKEN>
npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform ios --detached

如需完整的 Capawesome Cloud 设置指南，请参阅 capawesome-cloud。 如需 Capawesome CLI 参考，请参阅 capawesome-cli。

推送通知

通过 @capacitor-firebase/messaging 使用 Firebase Cloud Messaging（FCM）设置推送通知：

npm install @capacitor-firebase/messaging firebase
npx cap sync

需要先设置 Firebase 项目、完成特定平台的配置（iOS 使用 APNs，Android 使用 google-services.json），并处理权限。

如需完整的设置指南，请参阅 capacitor-push-notifications。

应用内购买

使用以下任一方案设置应用内购买和订阅：

• Capawesome Purchases（@capawesome-team/capacitor-purchases）——轻量级，无需第三方后端，但需要 Capawesome Insiders 许可证。
• RevenueCat（@revenuecat/purchases-capacitor）——完整的托管后端，提供收据验证、分析和集成。

两种方案都需要在 App Store Connect（iOS）和／或 Google Play Console（Android）中配置产品。

如需完整的设置指南，请参阅 capacitor-in-app-purchases。

相关技能

• capacitor-app-creation -- 从头开始创建新的 Capacitor 应用。
• capacitor-app-development -- Capacitor 开发主题、配置和故障排查。
• capacitor-angular -- Angular 专属的 Capacitor 模式。
• capacitor-react -- React 专属的 Capacitor 模式。
• capacitor-vue -- Vue 专属的 Capacitor 模式。
• capacitor-plugins -- 安装和配置 160 多个 Capacitor 插件。
• capacitor-plugin-development -- 创建自定义 Capacitor 插件。
• capacitor-app-upgrades -- 跨主要版本升级 Capacitor 应用。
• capacitor-plugin-upgrades -- 跨主要版本升级 Capacitor 插件。
• capacitor-push-notifications -- 使用 FCM 推送通知。
• capacitor-in-app-purchases -- 应用内购买和订阅。
• capawesome-cloud -- 实时更新、原生构建和应用商店发布。
• capawesome-cli -- Capawesome CLI 参考。
• capawesome-mcp -- 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。
• capacitor-mcp -- 将 MCP 客户端连接到托管的 Capacitor MCP 服务，以获取最新的 Capacitor 文档和插件列表。