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 (4→5, 5→6, 6→7, or 7→8).

将Capacitor插件升级至更高的主版本（4→5、5→6、6→7或7→8）。

Prerequisites

前置条件

Target Version	Node.js
5	16+
6	18+
7	20+
8	22+

The project must be a Capacitor plugin (not an app project).

目标版本	Node.js
5	16+
6	18+
7	20+
8	22+

项目必须是Capacitor插件项目（而非应用项目）。

Procedures

操作步骤

Step 1: Detect Current Version

步骤1：检测当前版本

Read

@capacitor/core

version from

package.json

(

devDependencies

peerDependencies

). Determine the current major version.

Ask the user for the target version. Default to the latest (8) if not specified.

从

package.json

的

devDependencies

或

peerDependencies

中读取

@capacitor/core

的版本，确定当前的主版本。

向用户确认目标版本。若未指定，则默认使用最新版本（8）。

Step 2: Execute Upgrade

步骤2：执行升级

For each major version jump between the current and target version, apply the corresponding upgrade guide sequentially:

Current → Target	Reference
4 → 5	`references/upgrade-v4-to-v5.md`
5 → 6	`references/upgrade-v5-to-v6.md`
6 → 7	`references/upgrade-v6-to-v7.md`
7 → 8	`references/upgrade-v7-to-v8.md`

For multi-version jumps (e.g., 5 → 8), apply each upgrade in order:

Read and apply
```
references/upgrade-v5-to-v6.md
```
Run
```
npm install && npx cap sync
```
, build, and verify the plugin's test/example app
Read and apply
```
references/upgrade-v6-to-v7.md
```
Run
```
npm install && npx cap sync
```
, build, and verify the plugin's test/example app
Read and apply
```
references/upgrade-v7-to-v8.md
```
Run
```
npm install && npx cap sync
```
, build, and verify the plugin's test/example app

Do not skip intermediate versions.

对于当前版本与目标版本之间的每一次主版本跨越，依次应用对应的升级指南：

当前→目标	参考文档
4 → 5	`references/upgrade-v4-to-v5.md`
5 → 6	`references/upgrade-v5-to-v6.md`
6 → 7	`references/upgrade-v6-to-v7.md`
7 → 8	`references/upgrade-v7-to-v8.md`

对于跨多版本跳转的升级（例如5→8），需按顺序执行每一步升级：

阅读并应用
```
references/upgrade-v5-to-v6.md
```
中的内容
运行
```
npm install && npx cap sync
```
，构建并验证插件的测试/示例应用
阅读并应用
```
references/upgrade-v6-to-v7.md
```
中的内容
运行
```
npm install && npx cap sync
```
，构建并验证插件的测试/示例应用
阅读并应用
```
references/upgrade-v7-to-v8.md
```
中的内容
运行
```
npm install && npx cap sync
```
，构建并验证插件的测试/示例应用

请勿跳过中间版本。

Step 3: Final Verification

步骤3：最终验证

After completing all upgrade steps:

bash

npm install
npx cap sync

Build the plugin's test/example app on both platforms to verify.

完成所有升级步骤后：

bash

npm install
npx cap sync

在两个平台上构建插件的测试/示例应用以验证升级效果。

Error Handling

错误处理

If automated upgrade tools fail, check the terminal output for which steps failed and apply those manually using the steps in the corresponding reference file.
If Android build fails after upgrade, run Tools > AGP Upgrade Assistant in Android Studio.
If iOS build fails, verify the deployment target matches the target version requirements in the reference file.
If Gradle property syntax warnings appear (v8+), search all
```
.gradle
```
files for property assignments without
```
=
```
and update them.
If a multi-version upgrade fails mid-way, fix the current version step before proceeding to the next.

如果自动化升级工具失败，检查终端输出以确定哪一步失败，然后使用对应参考文档中的步骤手动执行该部分操作。
如果升级后Android构建失败，在Android Studio中运行Tools > AGP Upgrade Assistant。
如果iOS构建失败，验证部署目标是否符合参考文档中目标版本的要求。
如果出现Gradle属性语法警告（v8+），搜索所有
```
.gradle
```
文件，找到没有使用
```
=
```
的属性赋值并进行更新。
如果跨多版本升级中途失败，先修复当前版本的问题，再继续下一步升级。