ionic-app-upgrades

Ionic 应用升级

将 Ionic Framework 应用升级到较新的主版本（4 到 5、5 到 6、6 到 7 或 7 到 8）。

前置条件

目标版本	Angular	React	Vue
5	8.2+	16+	N/A
6	12+	17+	3.0.6+
7	14+	17+	3.0.6+
8	16+	17+	3.0.6+

流程

步骤 1：检测当前版本

从 package.json（dependencies 或 devDependencies）中读取 @ionic/angular、@ionic/react 或 @ionic/vue 的版本。确定当前主版本，以及使用的框架（Angular、React、Vue 或 Core/Standalone）。

询问用户目标版本。如果未指定，默认使用最新版本（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 run build），修复所有错误，并确认应用能够运行
3. 阅读并应用 references/upgrade-v6-to-v7.md
4. 构建项目（npm run build），修复所有错误，并确认应用能够运行
5. 阅读并应用 references/upgrade-v7-to-v8.md
6. 构建项目（npm run build），修复所有错误，并确认应用能够运行

不要跳过中间版本。

步骤 3：最终验证

完成所有升级步骤后：

npm run build

如果项目使用 Capacitor，也要运行：

npx cap sync

错误处理

• 如果升级步骤后 npm run build 失败，请检查编译器错误。大多数错误由已移除的组件属性、已重命名的 CSS 变量或已更改的事件处理程序签名导致，相关说明见参考文件。
• 如果 Jest 或单元测试失败，请检查 transformIgnorePatterns 配置——Ionic 6+ 以 ES Modules 形式发布，需要更新 Babel/Jest 配置。
• 如果升级后 CSS 样式失效，请检查该版本参考文件中已移除的 CSS Shadow Parts 和已重命名的 CSS 变量。
• 如果跨多个版本的升级中途失败，请先修复当前版本的升级问题，再继续下一步。
• 如果项目也使用 Capacitor，且平台构建失败，可能还需要升级 Capacitor 版本——请使用 capacitor-app-upgrades 技能。

相关技能

• capacitor-app-upgrades — 如果 Ionic 升级时也需要升级 Capacitor，请使用此技能了解 Capacitor 专属升级步骤。
• ionic-app-development — Ionic 开发通用指南。
• capacitor-plugins — 应用升级后用于安装或重新配置插件。