capacitor-app-upgrades

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor App Upgrade

Capacitor应用升级

Upgrade a Capacitor app project 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	Xcode	Android Studio
5	16+	14.1+	Flamingo 2022.2.1+ (Java 17)
6	18+	15.0+	Hedgehog 2023.1.1+
7	20+	16.0+	Ladybug 2024.2.1+ (Java 21)
8	22+	26.0+	Otter 2025.2.1+

目标版本	Node.js	Xcode	Android Studio
5	16+	14.1+	Flamingo 2022.2.1+（Java 17）
6	18+	15.0+	Hedgehog 2023.1.1+
7	20+	16.0+	Ladybug 2024.2.1+（Java 21）
8	22+	26.0+	Otter 2025.2.1+

Procedures

操作步骤

Step 1: Detect Current Version

步骤1：检测当前版本

Read

@capacitor/core

version from

package.json

(

dependencies

devDependencies

). Determine the current major version.

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

从

package.json

的

dependencies

或

devDependencies

中读取

@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
```
npx cap sync
```
, build, and verify on both platforms
Read and apply
```
references/upgrade-v6-to-v7.md
```
Run
```
npx cap sync
```
, build, and verify on both platforms
Read and apply
```
references/upgrade-v7-to-v8.md
```
Run
```
npx cap sync
```
, build, and verify on both platforms

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
```
中的内容
运行
```
npx cap sync
```
，在两个平台上构建并验证
阅读并应用
```
references/upgrade-v6-to-v7.md
```
中的内容
运行
```
npx cap sync
```
，在两个平台上构建并验证
阅读并应用
```
references/upgrade-v7-to-v8.md
```
中的内容
运行
```
npx cap sync
```
，在两个平台上构建并验证

请勿跳过中间版本。

Step 3: Final Verification

步骤3：最终验证

After completing all upgrade steps:

bash

npx cap sync
npx cap run android
npx cap run ios

完成所有升级步骤后：

bash

npx cap sync
npx cap run android
npx cap run ios

Error Handling

错误处理

If
```
npx cap migrate
```
fails partially, 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.

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