capacitor-plugin-upgrades

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor Plugin Upgrade

Capacitor插件升级

Upgrade a Capacitor plugin to a newer major version.

升级Capacitor插件至新的主版本。

When to Use This Skill

适用场景

User wants to bump a Capacitor plugin package to a newer major version
User needs help adapting native code to a new Capacitor major release
User wants to verify the plugin still works in its example app after the upgrade

用户需要将Capacitor插件包升级到新的主版本
用户需要协助适配原生代码以适配Capacitor新的主版本发布
用户希望验证升级后插件在其示例应用中仍可正常运行

Live Project Snapshot

项目实时快照

Plugin and Capacitor package snapshot: !

node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

Example and native project paths: !

find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' \)

插件和Capacitor包快照: !

node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

示例和原生项目路径: !

find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' \)

Procedures

操作流程

Step 1: Detect the Current Version

步骤1: 检测当前版本

Start from the injected snapshot above, then inspect

package.json

if the Capacitor ranges or package version need confirmation.

Ask the user to confirm the exact target major version before proceeding.

从上方注入的快照开始，若需要确认Capacitor版本范围或包版本，可查看

package.json

。

在继续操作前，请用户确认确切的目标主版本。

Step 2: Upgrade Sequentially

步骤2: 按顺序升级

For each major jump:

Update
```
@capacitor/*
```
peer dependencies and native bridge code as needed.
Adjust iOS and Android native project settings for the target Capacitor version.
Run
```
npm install
```
.
Run
```
npx cap sync
```
from the example or test app directory that contains
```
capacitor.config.*
```
, or rebuild that app with the repository's documented command.
Verify the plugin API still works in the example app or test app.

Do not skip intermediate major versions.

每次跨一个主版本升级时:

根据需要更新
```
@capacitor/*
```
对等依赖和原生桥接代码。
针对目标Capacitor版本调整iOS和Android原生项目设置。
运行
```
npm install
```
。
在包含
```
capacitor.config.*
```
的示例或测试应用目录下运行
```
npx cap sync
```
，或者使用仓库文档中记录的命令重建该应用。
验证插件API在示例应用或测试应用中仍可正常工作。

请勿跳过中间的主版本。

Step 3: Check Plugin-Specific Surface Area

步骤3: 检查插件特定的对外接口

Review these plugin areas carefully:

TypeScript definitions and exported names
Native method signatures and return payloads
Android namespace, Gradle settings, and Java compatibility
iOS deployment target, Swift syntax, and bridge registration
Documentation snippets and README install steps

仔细检查以下插件区域:

TypeScript定义和导出名称
原生方法签名和返回负载
Android命名空间、Gradle设置和Java兼容性
iOS部署目标、Swift语法和桥接注册
文档片段和README安装步骤

Step 4: Final Verification

步骤4: 最终验证

Check whether

npm run verify

exists in

package.json

or the repository scripts.

If it exists, run:

bash

npm run verify

If it does not exist, run the repository's documented fallback checks instead:

```
npm run build
```
```
npm test
```
```
npx cap sync
```
from the example/test app directory
the example app or test app build for every shipped platform

Run the sync and build commands from the plugin's example/test app directory, not the plugin root.

检查

package.json

或仓库脚本中是否存在

npm run verify

。

如果存在，运行:

bash

npm run verify

如果不存在，运行仓库文档中记录的备选检查项:

```
npm run build
```
```
npm test
```
在示例/测试应用目录下运行
```
npx cap sync
```
针对每个发布支持的平台构建示例应用或测试应用

请在插件的示例/测试应用目录下运行同步和构建命令，不要在插件根目录下运行。

Error Handling

错误处理

If a migration tool exists for the target version, use it first and then review the diff manually.
If the example app breaks, fix the plugin API or native wiring before publishing the version bump.
If a plugin supports multiple platforms, verify every platform that ships in the package.

如果目标版本存在迁移工具，请先使用该工具，然后手动审查差异。
如果示例应用崩溃，在发布版本升级前修复插件API或原生连接逻辑。
如果插件支持多平台，请验证包中发布的所有平台。