capacitor-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor Expert

Capacitor 专家指南

Comprehensive reference for building cross-platform apps with Capacitor. Covers architecture, CLI, plugins, framework integration, best practices, and Capawesome Cloud.

这是使用Capacitor构建跨平台应用的综合性参考文档，涵盖架构、CLI、插件、框架集成、最佳实践以及Capawesome Cloud相关内容。

Core Concepts

核心概念

Capacitor is a cross-platform native runtime for building web apps that run natively on iOS, Android, and the web. The web app runs in a native WebView, and Capacitor provides a bridge to native APIs via plugins.

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

Architecture

架构

A Capacitor app has three layers:

Web layer -- HTML/CSS/JS app running inside a native WebView (WKWebView on iOS, Android System WebView on Android).
Native bridge -- Serializes JS plugin calls, routes them to native code, and returns results as Promises.
Native layer -- Swift/ObjC (iOS) and Kotlin/Java (Android) code implementing native functionality.

Data passed across the bridge must be JSON-serializable. Pass files as paths, not base64.

Capacitor应用包含三层：

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

跨桥传递的数据必须可JSON序列化。文件需以路径形式传递，而非base64编码。

Project Structure

项目结构

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

The

android/

and

ios/

directories are full native projects -- they are committed to version control and can be modified directly.

my-app/
  android/                  # 原生Android项目（需提交到版本控制系统）
  ios/                      # 原生iOS项目（需提交到版本控制系统）
    App/
      App/                  # iOS应用源码文件
      App.xcodeproj/
  src/                      # Web应用源码
  dist/ or www/ or build/   # 构建后的Web资源
  capacitor.config.ts       # Capacitor配置文件
  package.json

android/

和

ios/

目录是完整的原生项目——需提交到版本控制系统，且可直接修改。

Capacitor Config

Capacitor 配置

capacitor.config.ts

(preferred) or

capacitor.config.json

controls app behavior:

typescript

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;

For details, see App Configuration.

capacitor.config.ts

（推荐）或

capacitor.config.json

用于控制应用行为：

typescript

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  server: {
    // androidScheme: 'https', // Cap 6+版本默认值
  },
};

export default config;

详细内容请查看应用配置。

Creating a New App

创建新应用

Quick Start

快速开始

bash

undefined

bash

undefined

1. Create a web app (React example with Vite)

1. 创建Web应用（以Vite创建React项目为例）

npm create vite@latest my-app -- --template react-ts cd my-app && npm install

2. Install Capacitor

2. 安装Capacitor

npm install @capacitor/core npm install -D @capacitor/cli

3. Initialize Capacitor

3. 初始化Capacitor

npx cap init "My App" com.example.myapp --web-dir dist

4. Build web assets

4. 构建Web资源

npm run build

5. Add platforms

5. 添加平台

npm install @capacitor/android @capacitor/ios npx cap add android npx cap add ios

6. Sync and run

6. 同步并运行

npx cap sync npx cap run android npx cap run ios


**Web asset directories by framework:**
- Angular: `dist/<project-name>/browser` (Angular 17+ with application builder)
- React (Vite): `dist`
- Vue (Vite): `dist`
- Vanilla: `www`

For the full guided creation flow, see [capacitor-app-creation](https://github.com/capawesome-team/skills/blob/main/skills/capacitor-app-creation/SKILL.md).

npx cap sync npx cap run android npx cap run ios


**各框架对应的Web资源目录：**
- Angular: `dist/<project-name>/browser`（Angular 17+搭配应用构建器）
- React (Vite): `dist`
- Vue (Vite): `dist`
- 原生Web: `www`

完整的引导式创建流程请查看[capacitor-app-creation](https://github.com/capawesome-team/skills/blob/main/skills/capacitor-app-creation/SKILL.md)。

Capacitor CLI

All commands:

npx cap <command>

. Most important commands:

Command	Purpose
`npx cap init <name> <id>`	Initialize Capacitor in a project
`npx cap add <platform>`	Add Android or iOS platform
`npx cap sync`	Copy web assets + update native dependencies (run after every plugin install, config change, or web build)
`npx cap copy`	Copy web assets only (faster, no native dependency update)
`npx cap run <platform>`	Build, sync, and deploy to device/emulator
`npx cap run <platform> -l --external`	Run with live reload
`npx cap open <platform>`	Open native project in IDE
`npx cap build <platform>`	Build native project
`npx cap doctor`	Diagnose configuration issues
`npx cap ls`	List installed plugins
`npx cap migrate`	Automated upgrade to newer Capacitor version

For the full CLI reference, see CLI Reference.

所有命令格式：

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`	列出已安装的插件
`npx cap migrate`	自动升级到新版本的Capacitor

完整的CLI参考请查看CLI参考文档。

Framework Integration

框架集成

Capacitor works with any web framework. Framework-specific patterns:

Capacitor可与任意Web框架配合使用。以下是各框架的特定模式：

Angular

Wrap Capacitor plugins in Angular services for DI and testability.
Plugin event listeners run outside NgZone -- always wrap callbacks in
```
NgZone.run()
```
.
Register listeners in
```
ngOnInit
```
, remove in
```
ngOnDestroy
```
.

For details, see capacitor-angular.

将Capacitor插件封装到Angular服务中，以支持依赖注入和可测试性。
插件事件监听器在NgZone外部运行——务必将回调函数包裹在
```
NgZone.run()
```
中。
在
```
ngOnInit
```
中注册监听器，在
```
ngOnDestroy
```
中移除。

详细内容请查看capacitor-angular。

React

Create custom hooks (
```
useCamera
```
,
```
useNetwork
```
) that wrap Capacitor plugins.
Use
```
useEffect
```
for listener registration with cleanup to prevent memory leaks.
React 18 strict mode double-mounts -- ensure cleanup functions work correctly.

For details, see capacitor-react.

创建自定义Hook（如
```
useCamera
```
、
```
useNetwork
```
）来封装Capacitor插件。
使用
```
useEffect
```
注册监听器并添加清理逻辑，以防止内存泄漏。
React 18严格模式会触发双重挂载——确保清理函数能正常工作。

详细内容请查看capacitor-react。

Vue

Create composables (
```
useCamera
```
,
```
useNetwork
```
) using Vue 3 Composition API.
Register listeners in
```
onMounted
```
, remove in
```
onUnmounted
```
.
Vue reactivity picks up
```
ref
```
changes automatically (no NgZone equivalent needed).

For details, see capacitor-vue.

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

详细内容请查看capacitor-vue。

Plugins

插件

Plugins are Capacitor's extension mechanism. Each plugin exposes a JS API backed by native implementations.

插件是Capacitor的扩展机制，每个插件都暴露一个JS API，背后由原生实现支撑。

Plugin Sources

插件来源

Official (
```
@capacitor/*
```
) -- Camera, Filesystem, Geolocation, Preferences, etc.
Capawesome (
```
@capawesome/*
```
,
```
@capawesome-team/*
```
) -- SQLite, NFC, Biometrics, Live Update, etc.
Community (
```
@capacitor-community/*
```
) -- AdMob, BLE, SQLite, Stripe, etc.
Firebase (
```
@capacitor-firebase/*
```
) -- Analytics, Auth, Messaging, Firestore, etc.
MLKit (
```
@capacitor-mlkit/*
```
) -- Barcode scanning, face detection, translation.
RevenueCat (
```
@revenuecat/purchases-capacitor
```
) -- In-app purchases.

官方插件（
```
@capacitor/*
```
）—— 如Camera、Filesystem、Geolocation、Preferences等。
Capawesome插件（
```
@capacitor/*
```
,
```
@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
```
）—— 内购功能。

Installing a Plugin

安装插件

bash

npm install @capacitor/camera
npx cap sync

After installation, apply any required platform configuration (permissions in

AndroidManifest.xml

Info.plist

entries, etc.) as documented by the plugin.

bash

npm install @capacitor/camera
npx cap sync

安装完成后，需按照插件文档配置平台相关设置（如

AndroidManifest.xml

中的权限、

Info.plist

中的条目等）。

Using a Plugin

使用插件

typescript

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

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

For the full plugin index (160+ plugins) and setup guides, see capacitor-plugins.

typescript

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

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

完整的插件索引（160+个插件）和设置指南请查看capacitor-plugins。

Plugin Development

插件开发

Create custom Capacitor plugins with native iOS (Swift) and Android (Java/Kotlin) implementations:

Scaffold with
```
npm init @capacitor/plugin@latest
```
.
Define the TypeScript API in
```
src/definitions.ts
```
.
Implement the web layer in
```
src/web.ts
```
.
Implement iOS plugin in
```
ios/Sources/
```
.
Implement Android plugin in
```
android/src/main/java/
```
.
Verify with
```
npm run verify
```
.

Key rules:

The

registerPlugin()

name in

src/index.ts

must match

jsName

on iOS and

@CapacitorPlugin(name = "...")

on Android.

iOS methods need
```
@objc
```
and must be listed in
```
pluginMethods
```
(CAPBridgedPlugin).
Android methods need
```
@PluginMethod()
```
annotation and must be
```
public
```
.

For full details, see capacitor-plugin-development.

创建自定义Capacitor插件，需包含原生iOS（Swift）和Android（Java/Kotlin）实现：

使用
```
npm init @capacitor/plugin@latest
```
生成脚手架。
在
```
src/definitions.ts
```
中定义TypeScript API。
在
```
src/web.ts
```
中实现Web层逻辑。
在
```
ios/Sources/
```
中实现iOS插件。
在
```
android/src/main/java/
```
中实现Android插件。
使用
```
npm run verify
```
验证插件。

关键规则：

src/index.ts

中

registerPlugin()

的名称必须与iOS端的

jsName

和Android端的

@CapacitorPlugin(name = "...")

匹配。

iOS方法需添加
```
@objc
```
注解，且必须在
```
pluginMethods
```
（CAPBridgedPlugin）中列出。
Android方法需添加
```
@PluginMethod()
```
注解，且必须是
```
public
```
的。

详细内容请查看capacitor-plugin-development。

Cross-Platform Best Practices

跨平台最佳实践

Platform Detection

平台检测

typescript

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

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

typescript

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

const platform = Capacitor.getPlatform(); // 'android' | 'ios' | 'web'
if (Capacitor.isNativePlatform()) { /* 仅原生平台执行的代码 */ }
if (Capacitor.isPluginAvailable('Camera')) { /* 插件可用时执行的代码 */ }

Permissions

权限处理

Follow the check-then-request pattern:

typescript

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({ ... });

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

typescript

const status = await Camera.checkPermissions();
if (status.camera !== 'granted') {
  const requested = await Camera.requestPermissions();
  if (requested.camera === 'denied') {
    // 引导用户到应用设置——iOS上无法再次请求权限
    return;
  }
}
const photo = await Camera.getPhoto({ ... });

Performance

性能优化

Minimize bridge calls -- batch operations instead of many individual calls.
Use file paths over base64 for binary data.
Lazy-load plugins with dynamic imports for code splitting.

减少桥接调用 —— 批量操作，而非多次单独调用。
使用文件路径 而非base64处理二进制数据。
懒加载插件 —— 使用动态导入实现代码分割。

Error Handling

错误处理

Always wrap plugin calls in try-catch:

typescript

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);
  }
}

For full details, see Cross-Platform Best Practices.

务必将插件调用包裹在try-catch块中：

typescript

try {
  const photo = await Camera.getPhoto({ resultType: CameraResultType.Uri });
} catch (error) {
  if (error.message === 'User cancelled photos app') {
    // 非错误场景
  } else {
    console.error('相机错误:', error);
  }
}

详细内容请查看跨平台最佳实践。

Deep Links

深度链接

Deep links open specific content in the app from external URLs.

iOS: Universal Links via

apple-app-site-association

hosted at

https://<domain>/.well-known/

Android: App Links via

assetlinks.json

hosted at

https://<domain>/.well-known/

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

iOS：通过
```
apple-app-site-association
```
文件配置通用链接，该文件需托管在
```
https://<domain>/.well-known/
```
路径下。
Android：通过
```
assetlinks.json
```
配置应用链接，该文件需托管在
```
https://<domain>/.well-known/
```
路径下。

Listener Setup

监听器设置

typescript

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

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

typescript

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

App.addListener('appUrlOpen', (event) => {
  const path = new URL(event.url).pathname;
  // 路由到对应的页面
});

Platform Configuration

平台配置

iOS: Add

applinks:<domain>

to Associated Domains capability in

ios/App/App/App.entitlements

Android: Add

<intent-filter android:autoVerify="true">

android/app/src/main/AndroidManifest.xml

For full setup, see Deep Links.

iOS：在

ios/App/App/App.entitlements

中添加

applinks:<domain>

到关联域名能力中。

Android：在

android/app/src/main/AndroidManifest.xml

中添加

<intent-filter android:autoVerify="true">

。

完整设置指南请查看深度链接。

Storage

存储方案

Requirement	Solution
App settings, preferences	`@capacitor/preferences` (native key-value, persists reliably)
Sensitive data (tokens, credentials)	`@capawesome-team/capacitor-secure-preferences` (Keychain/Keystore)
Relational data, offline-first	SQLite ( `@capawesome-team/capacitor-sqlite` or `@capacitor-community/sqlite` )
Files, images, documents	`@capacitor/filesystem`

Do NOT use

localStorage

IndexedDB

, or cookies for persistent data -- the OS can evict them (especially on iOS).

For details, see Storage.

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

请勿使用

localStorage

、

IndexedDB

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

详细内容请查看存储方案。

Security

安全建议

Never embed secrets (API keys with write access, OAuth secrets, DB credentials) in client code -- move to a server API.

Use secure storage (

@capawesome-team/capacitor-secure-preferences

) for tokens and credentials, not

localStorage

@capacitor/preferences

HTTPS only -- never allow cleartext HTTP in production.
Content Security Policy -- add a
```
<meta>
```
CSP tag in
```
index.html
```
.

Disable WebView debugging in production: set

webContentsDebuggingEnabled: false

capacitor.config.ts

Prefer Universal/App Links over custom URL schemes (verified via HTTPS).
iOS Privacy Manifest (
```
PrivacyInfo.xcprivacy
```
) -- required for iOS 17+ when using privacy-sensitive APIs.

For details, see Security.

切勿嵌入敏感信息（具有写入权限的API密钥、OAuth密钥、数据库凭证）到客户端代码中——应将其迁移到服务器API。

使用安全存储（

@capawesome-team/capacitor-secure-preferences

）存储令牌和凭证，而非

localStorage

或

@capacitor/preferences

。

仅使用HTTPS —— 生产环境中绝不允许明文HTTP。
内容安全策略 —— 在
```
index.html
```
中添加
```
<meta>
```
标签形式的CSP。

生产环境禁用WebView调试：在

capacitor.config.ts

中设置

webContentsDebuggingEnabled: false

。

优先使用通用链接/应用链接 而非自定义URL scheme（通过HTTPS验证）。
iOS隐私清单（
```
PrivacyInfo.xcprivacy
```
）—— iOS 17+中使用隐私敏感API时必须配置。

详细内容请查看安全建议。

Testing

测试指南

Unit Testing

单元测试

Mock Capacitor plugins in Jest/Vitest since tests run in Node.js, not a WebView:

typescript

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

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

typescript

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

E2E Testing

端到端测试

Web E2E: Cypress or Playwright (tests web layer, plugins must be mocked).
Native E2E: Appium (cross-platform) or Detox (iOS-focused).

Web端E2E：使用Cypress或Playwright（测试Web层，插件需模拟）。
原生端E2E：使用Appium（跨平台）或Detox（专注iOS）。

Debugging

调试方法

Android: Enable

webContentsDebuggingEnabled: true

, open

chrome://inspect

in Chrome.

iOS: Enable
```
webContentsDebuggingEnabled: true
```
, use Safari > Develop menu > select device.

For details, see Testing.

Android：启用

webContentsDebuggingEnabled: true

，在Chrome中打开

chrome://inspect

。

iOS：启用
```
webContentsDebuggingEnabled: true
```
，使用Safari > 开发菜单 > 选择设备。

详细内容请查看测试指南。

Troubleshooting

故障排除

Android

npx cap sync
fails: Verify

@capacitor/core

and

@capacitor/cli

versions match. Run

cd android && ./gradlew clean

Build fails after config changes: Clean with
```
cd android && ./gradlew clean
```
, then rebuild.
Plugin not found at runtime: Run
```
npx cap sync
```
after plugin installation. Verify Gradle sync completed.
SDK errors: Verify
```
ANDROID_HOME
```
is set. Install missing SDK versions via Android Studio SDK Manager.
White square notification icon: Push notification icons must be white pixels on transparent background.

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管理器安装缺失的SDK版本。
通知图标显示白色方块：推送通知图标必须是透明背景的白色像素图。

iOS

Build fails with "no such module": Run

npx cap sync ios

. For CocoaPods:

cd ios/App && pod install --repo-update

Build fails after config changes: Clean build folder (Xcode Product > Clean Build Folder) or delete
```
ios/App/Pods
```
and re-run
```
pod install
```
.
Simulator cannot receive push notifications: Use a physical device for push notification testing.
Permission denied permanently: Cannot re-request on iOS. Guide user to Settings > App > Permissions.
WebView not loading: Verify
```
webDir
```
in
```
capacitor.config.ts
```
matches the actual build output directory.

构建失败提示"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上无法再次请求权限，需引导用户到设置 > 应用 > 权限中开启。
WebView无法加载：验证
```
capacitor.config.ts
```
中的
```
webDir
```
是否与实际构建输出目录匹配。

General

通用问题

Live reload not connecting: Ensure device and dev machine are on the same network. Use
```
--external
```
flag.
Plugin not found: Run
```
npx cap sync
```
. Verify plugin is in
```
package.json
```
dependencies.

Capacitor is not defined
: Install

@capacitor/core

(

npm install @capacitor/core

For full troubleshooting, see Android Troubleshooting and iOS Troubleshooting.

实时重载无法连接：确保设备和开发机器在同一网络中，使用
```
--external
```
参数。
找不到插件：运行
```
npx cap sync
```
。验证插件是否在
```
package.json
```
的依赖中。

Capacitor is not defined
：安装

@capacitor/core

（

npm install @capacitor/core

）。

完整的故障排除指南请查看Android故障排除和iOS故障排除。

Upgrading

版本升级

Capacitor supports upgrades across major versions (4 through 8). Apply each major version jump sequentially -- do not skip intermediate versions.

Current to Target	Node.js	Xcode	Android Studio
to 5	16+	14.1+	Flamingo 2022.2.1+
to 6	18+	15.0+	Hedgehog 2023.1.1+
to 7	20+	16.0+	Ladybug 2024.2.1+
to 8	22+	26.0+	Otter 2025.2.1+

Quick automated upgrade:

bash

npx cap migrate
npx cap sync

npx cap migrate

fails partially, apply manual steps from the upgrade guides.

For app upgrades, see capacitor-app-upgrades. For plugin upgrades, see capacitor-plugin-upgrades.

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+

快速自动升级：

bash

npx cap migrate
npx cap sync

如果

npx cap migrate

部分执行失败，请按照升级指南手动执行步骤。

应用升级请查看capacitor-app-upgrades。插件升级请查看capacitor-plugin-upgrades。

Capawesome Cloud

Capawesome Cloud provides cloud infrastructure for Capacitor apps: native builds, live updates, and automated app store publishing.

Website: capawesome.io | Cloud Services: cloud.capawesome.io

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

官网：capawesome.io | 云服务：cloud.capawesome.io

Getting Started

快速开始

bash

undefined

bash

undefined

Install and authenticate

安装并认证

npx @capawesome/cli login

Create an app

创建应用

npx @capawesome/cli apps:create

undefined

npx @capawesome/cli apps:create

undefined

Live Updates

实时更新

Deploy over-the-air (OTA) web updates to Capacitor apps without going through the app stores. Users receive updates immediately on next app launch.

Setup:

bash

undefined

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

设置步骤：

bash

undefined

Install the live update plugin

安装实时更新插件

npm install @capawesome/capacitor-live-update npx cap sync


Configure in `capacitor.config.ts`:

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

Deploy an update:

bash

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

npm install @capawesome/capacitor-live-update npx cap sync


在`capacitor.config.ts`中配置：

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

推送更新：

bash

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

Native Builds

原生构建

Build iOS and Android apps in the cloud without local build environments. Supports signing certificates, environments, and build configuration.

bash

undefined

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

bash

undefined

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>

undefined

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

undefined

App Store Publishing

应用商店发布

Automate submissions to Apple App Store (TestFlight) and Google Play Store.

bash

undefined

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

bash

undefined

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>

undefined

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

undefined

CI/CD Integration

CI/CD集成

Use token-based auth for CI/CD pipelines:

bash

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

For full Capawesome Cloud setup, see capawesome-cloud. For the Capawesome CLI reference, see capawesome-cli.

使用基于令牌的认证方式集成到CI/CD流水线：

bash

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。

Push Notifications

推送通知

Set up push notifications using Firebase Cloud Messaging (FCM) via

@capacitor-firebase/messaging

bash

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

Requires Firebase project setup, platform-specific configuration (APNs for iOS,

google-services.json

for Android), and permission handling.

For the full setup guide, see capacitor-push-notifications.

使用Firebase Cloud Messaging（FCM）通过

@capacitor-firebase/messaging

设置推送通知：

bash

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

需要配置Firebase项目、平台特定设置（iOS的APNs、Android的

google-services.json

）以及权限处理。

完整的设置指南请查看capacitor-push-notifications。

In-App Purchases

内购功能

Set up in-app purchases and subscriptions with either:

Capawesome Purchases (
```
@capawesome-team/capacitor-purchases
```
) -- lightweight, no third-party backend, requires Capawesome Insiders license.
RevenueCat (
```
@revenuecat/purchases-capacitor
```
) -- full managed backend with receipt validation, analytics, and integrations.

Both require App Store Connect (iOS) and/or Google Play Console (Android) product configuration.

For the full setup guide, see capacitor-in-app-purchases.

可通过以下两种方式设置内购和订阅：

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

两者都需要在App Store Connect（iOS）和/或Google Play Console（Android）中配置产品。

完整的设置指南请查看capacitor-in-app-purchases。