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.

将Capacitor应用项目升级到新的主版本。

When to Use This Skill

何时使用该技能

User wants to move a Capacitor app from one major version to another
User is preparing for a multi-version jump
User needs a safe fallback when automated migration does not complete cleanly

用户需要将Capacitor应用从一个主版本迁移到另一个主版本
用户准备进行跨多个版本的升级
当自动迁移无法顺利完成时，用户需要安全的回退方案

Live Project Snapshot

项目实时快照

Current Capacitor packages from

package.json

: !

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=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

Native and Capacitor config paths: !

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

从

package.json

中获取当前的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=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

原生配置与Capacitor配置路径： !

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

Procedures

操作流程

Step 1: Detect the Current Version

步骤1：检测当前版本

Start from the injected snapshot above, then confirm

@capacitor/core

package.json

if anything looks inconsistent.

If the target version is not specified, ask the user to confirm an explicit major version before proceeding.

从上方注入的快照开始，如果有任何不一致的地方，请核对

package.json

中的

@capacitor/core

版本。如果未指定目标版本，请先让用户确认明确的主版本号，再继续操作。

Step 2: Upgrade One Major Version at a Time

步骤2：每次仅升级一个主版本

Do not skip intermediate major versions.

For each version jump:

Update the
```
@capacitor/*
```
package versions in
```
package.json
```
.
Run
```
npm install
```
.
Run the Capacitor migration flow if available for that version.
Sync native projects with
```
npx cap sync
```
.
Verify iOS and Android build cleanly before continuing.

If the automated migration step fails, apply the generated changes manually and continue with the same major version before moving to the next one.

不要跳过中间的主版本。

每次版本升级的操作：

更新
```
package.json
```
中所有
```
@capacitor/*
```
包的版本。
运行
```
npm install
```
。
如果对应版本有Capacitor迁移流程，请运行该流程。
执行
```
npx cap sync
```
同步原生项目。
继续升级前先验证iOS和Android可以正常构建。

如果自动迁移步骤失败，请手动应用生成的变更，在当前主版本处理完成后再升级到下一个版本。

Step 3: Check Native Projects

步骤3：检查原生项目

Review the platform projects for version-specific requirements:

iOS deployment target
Xcode compatibility
Android Gradle Plugin and Java version
Any plugin-specific native changes introduced by the new Capacitor major version

检查平台项目是否满足对应版本的特定要求：

iOS部署目标版本
Xcode兼容性
Android Gradle插件和Java版本
新的Capacitor主版本引入的任何插件相关的原生变更

Step 4: Final Verification

步骤4：最终验证

Run the project checks that matter for the app:

bash

npm install
npx cap sync
npx cap run ios
npx cap run android

If the app has a custom test or build pipeline, run that as well.

运行适用于当前应用的项目检查：

bash

npm install
npx cap sync
npx cap run ios
npx cap run android

如果应用有自定义的测试或构建流水线，也请运行对应的流程。

Error Handling

错误处理

If the automated migration step only partially completes, finish the current major version manually before trying the next one.
If iOS fails, verify the deployment target and Xcode version match the target Capacitor major version.
If Android fails, verify the Gradle and Java requirements for the target version.
If the app uses plugins with their own upgrade constraints, handle those plugins separately after the app version is stable.

如果自动迁移步骤仅部分完成，请先手动完成当前主版本的升级，再尝试升级到下一个版本。
如果iOS构建失败，请验证部署目标版本和Xcode版本是否符合目标Capacitor主版本的要求。
如果Android构建失败，请验证目标版本所需的Gradle和Java版本要求。
如果应用使用的插件有自身的升级限制，请在应用版本稳定后单独处理这些插件的升级。