capacitor-plugin-upgrades

Capacitor 插件升级

将 Capacitor 插件升级到较新的主版本（4→5、5→6、6→7 或 7→8）。

前置条件

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

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

操作步骤

第 1 步：检测当前版本

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

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

第 2 步：执行升级

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

当前版本 → 目标版本	参考文档
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. 运行 npm install && npx cap sync，构建并验证插件的测试/示例应用
3. 阅读并应用 references/upgrade-v6-to-v7.md
4. 运行 npm install && npx cap sync，构建并验证插件的测试/示例应用
5. 阅读并应用 references/upgrade-v7-to-v8.md
6. 运行 npm install && npx cap sync，构建并验证插件的测试/示例应用

不要跳过中间版本。

第 3 步：最终验证

完成所有升级步骤后：

npm install
npx cap sync

在两个平台上构建插件的测试/示例应用以进行验证。

错误处理

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

相关技能

• capacitor-app-upgrades — 如果应用项目本身也需要升级，请使用此技能。
• capacitor-plugin-spm-support — 将插件升级到 Capacitor 6+ 后，使用此技能添加 Swift Package Manager 支持。
• capacitor-plugin-development — 从头创建新的 Capacitor 插件，包括脚手架、原生实现和发布。