Back to Details

ionic-app-upgrades

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ionic App Upgrade

Ionic应用升级

Upgrade an Ionic Framework app to a newer major version (4 to 5, 5 to 6, 6 to 7, or 7 to 8).
将Ionic Framework应用升级到更高主版本（4到5、5到6、6到7或7到8）。

Prerequisites

前置条件

Target VersionAngularReactVue
58.2+16+N/A
612+17+3.0.6+
714+17+3.0.6+
816+17+3.0.6+
目标版本AngularReactVue
58.2+16+不适用
612+17+3.0.6+
714+17+3.0.6+
816+17+3.0.6+

Procedures

操作步骤

Step 1: Detect Current Version

步骤1：检测当前版本

Read 
@ionic/angular
, 
@ionic/react
, or 
@ionic/vue
version from 
package.json
(
dependencies
or 
devDependencies
). Determine the current major version and which framework is in use (Angular, React, Vue, or Core/Standalone).
Ask the user for the target version. Default to the latest (8) if not specified.
从
package.json
的
dependencies
或
devDependencies
中读取
@ionic/angular
、
@ionic/react
或
@ionic/vue
的版本，确定当前主版本以及使用的框架（Angular、React、Vue或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 to TargetReference
4 to 5
references/upgrade-v4-to-v5.md
5 to 6
references/upgrade-v5-to-v6.md
6 to 7
references/upgrade-v6-to-v7.md
7 to 8
references/upgrade-v7-to-v8.md
For multi-version jumps (e.g., 5 to 8), apply each upgrade in order:
  1. Read and apply 
    references/upgrade-v5-to-v6.md
  2. Build the project (
    npm run build
    ), fix any errors, and verify the app runs
  3. Read and apply 
    references/upgrade-v6-to-v7.md
  4. Build the project (
    npm run build
    ), fix any errors, and verify the app runs
  5. Read and apply 
    references/upgrade-v7-to-v8.md
  6. Build the project (
    npm run build
    ), fix any errors, and verify the app runs
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），按顺序执行每一次升级：
  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
    ），修复所有报错，验证应用可正常运行
不得跳过中间版本。

Step 3: Final Verification

步骤3：最终验证

After completing all upgrade steps:
bash
npm run build
If the project uses Capacitor, also run:
bash
npx cap sync
完成所有升级步骤后执行：
bash
npm run build
如果项目使用Capacitor，还需运行：
bash
npx cap sync

Error Handling

错误处理

  • If 
    npm run build
    fails after an upgrade step, check the compiler errors. Most errors are caused by removed component properties, renamed CSS variables, or changed event handler signatures documented in the reference files.
  • If Jest or unit tests fail, check the 
    transformIgnorePatterns
    configuration — Ionic 6+ ships as ES Modules and requires Babel/Jest configuration updates.
  • If CSS styles break after upgrade, check for removed CSS Shadow Parts and renamed CSS variables in the reference file for that version.
  • If a multi-version upgrade fails mid-way, fix the current version step before proceeding to the next.
  • If the project also uses Capacitor and platform builds fail, the Capacitor version may also need upgrading — use the 
    capacitor-app-upgrades
    skill.
  • 如果执行升级步骤后
    npm run build
    失败，检查编译器报错，大部分错误是由参考文档中记录的组件属性移除、CSS变量重命名或事件处理函数签名变更导致的。
  • 如果Jest或单元测试失败，检查
    transformIgnorePatterns
    配置——Ionic 6+以ES Modules形式发布，需要更新Babel/Jest配置。
  • 如果升级后CSS样式损坏，检查对应版本参考文档中已移除的CSS Shadow Parts和重命名的CSS变量。
  • 如果跨多版本升级中途失败，先修复当前版本步骤的问题再继续下一个版本的升级。
  • 如果项目同时使用Capacitor且平台构建失败，可能也需要升级Capacitor版本——使用
    capacitor-app-upgrades
    技能处理。

Related Skills

相关技能

  • capacitor-app-upgrades
     — If Capacitor also needs upgrading alongside Ionic, use this skill for the Capacitor-specific upgrade steps.
  • ionic-app-development
     — General Ionic development guidance.
  • capacitor-plugins
     — For installing or reconfiguring plugins after the app upgrade.
  • capacitor-app-upgrades
     —— 如果需要同时升级Ionic和Capacitor，使用该技能处理Capacitor专属的升级步骤。
  • ionic-app-development
     —— 通用Ionic开发指导。
  • capacitor-plugins
     —— 用于应用升级后安装或重新配置插件。