capacitor-app-upgrades

Capacitor 应用升级

将 Capacitor 应用项目升级到较新的主版本（4→5、5→6、6→7 或 7→8）。

前提条件

目标版本	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+

流程

步骤 1：检测当前版本

从 package.json（dependencies 或 devDependencies）中读取 @capacitor/core 版本，确定当前主版本。

询问用户目标版本。若未指定，默认为最新版本（8）。

步骤 2：执行升级

不要运行 npx cap migrate。 这是一个交互式命令，无法由 Agent 调用。请始终按照对应的参考文件中的步骤手动完成每次升级。

对于当前版本到目标版本之间的每次主版本升级，按顺序应用相应的升级指南：

当前版本 → 目标版本	参考文件
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），请按顺序逐个应用升级：

1. 阅读并应用 references/upgrade-v5-to-v6.md
2. 运行 npx cap sync，构建，并在两个平台上验证
3. 阅读并应用 references/upgrade-v6-to-v7.md
4. 运行 npx cap sync，构建，并在两个平台上验证
5. 阅读并应用 references/upgrade-v7-to-v8.md
6. 运行 npx cap sync，构建，并在两个平台上验证

不要跳过中间版本。

步骤 3：最终验证

完成所有升级步骤后：

npx cap sync
npx cap run android
npx cap run ios

错误处理

• 如果升级后 Android 构建失败，请在 Android Studio 中运行 Tools > AGP Upgrade Assistant。
• 如果 iOS 构建失败，请确认部署目标符合参考文件中针对目标版本的要求。
• 如果出现 Gradle 属性语法警告（v8+），请搜索所有 .gradle 文件，查找缺少 = 的属性赋值并进行更新。
• 如果跨多个版本的升级中途失败，请先修复当前版本步骤，再继续下一步。

相关技能

• capacitor-app-development — 完成升级后，了解一般 Capacitor 开发主题、故障排除和最佳实践。
• capacitor-plugin-upgrades — 如果项目包含也需要升级的 Capacitor 插件，请在应用升级后使用此技能。
• capacitor-plugins — 用于在应用升级后安装或重新配置插件。
• ionic-app-upgrades — 如果项目使用 Ionic Framework UI 库，可能还需要同时升级 Ionic 版本。