从 API 12 升级到 API 26：英语学习 App 的渐进式迁移路线图
一、引言
HarmonyOS API 版本从 12（5.0）到 26（7.0 Beta）经历了 4 个大版本升级。对于我们的英语学习 App 而言，这意味着需要在 11 个模块中同步适配 API 变更、替换废弃 API、并逐步接入新特性。
一次性升级所有模块风险高、工作量大。因此，我们制定了一条渐进式的迁移路线图——遵循"先编译通过 → 再新特性接入 → 后废弃 API 替换"的三步策略，按模块优先级分批验证，确保每个阶段都有可交付的中间产物。本文将从 API 变更分析入手，详细阐述各模块的迁移优先级和具体方案。
二、API 版本关键变更点
2.1 API 12 → API 20（5.0 → 6.0）
| 变更类型 | 具体内容 | 影响范围 |
|---|---|---|
| V2 装饰器 | 引入 @ObservedV2/@Trace/@ComponentV2/@Local/@Param | 全部组件 |
| 路由系统 | NavPathStack 取代 router.replace | features 模块 |
| 音频 API | Media Kit 重构，AVPlayer 变更 | AudioPlayer |
| 资源管理 | $r 引用规范变化 | UI 全局 |
2.2 API 20 → API 21（6.0.0）
| 变更类型 | 具体内容 | 影响范围 |
|---|---|---|
| ContainerReader | 新增容器断点组件 | 布局组件 |
| systemMaterial | 新增系统材质属性 | UI 全局 |
| Live View | 实况窗 API | 学习页面 |
| @ReusableV2 | 全局复用池 | 列表组件 |
2.3 API 21 → API 23（6.1.0）
| 变更类型 | 具体内容 | 影响范围 |
|---|---|---|
| 方舟引擎 | GC 优化、渲染加速 | 全部 |
| HMAF | 智能体框架 | 首页、推荐 |
| 端云大模型 | AI Kit 统一接口 | AI 功能 |
2.4 API 23 → API 26（7.0 Beta）
| 变更类型 | 具体内容 | 影响范围 |
|---|---|---|
| AgentCard | 智能体卡片 | 桌面入口 |
| ArkTS Skill | 脚本扩展 | 挑战、报告 |
| 星盾安全 | 加密存储、TEE | 数据持久化 |
| 纯血鸿蒙 | 移除 APK 兼容层 | 全部 |
| FrameNode | 帧级更新 | 动画组件 |
三、废弃 API 替换方案
3.1 @State → @Local/@Param
这是 API 20 引入 V2 装饰器体系后最大的变更。迁移方案：
// 旧方案（API 12）@Componentexportstruct WordCardComponent{@StatewordText:string='';@Propmeaning:string='';build(){Text(this.wordText)}}// 新方案（API 20+）@ComponentV2exportstruct WordCardComponent{@LocalwordText:string='';// 组件内部状态@Parammeaning:string='';// 父组件传入数据（只读）build(){Text(this.wordText)}}迁移要点：
@State→@Local：保持内部可变状态@Prop→@Param：保持只读父传数据@Link→ 回调函数：子组件通过回调通知父组件
3.2 其他废弃 API
| 废弃 API | 替换方案 | 受影响模块 |
|---|---|---|
router.replace() | NavPathStack.pushPath() | features 模块 |
@Observed | @ObservedV2 | 数据模型 |
window.getLastWindow() | UIAbilityContext.getWindow() | EntryAbility |
media.createAVPlayer() | avPlayer.createAVPlayer() | AudioPlayer |
四、模块兼容性配置策略
在迁移过程中，不同模块需要设置不同的兼容版本：
// commonLib/oh-package.json5 — 核心库，最低兼容 API 12 { "apiType": "stageMode", "minAPIVersion": 12, "targetAPIVersion": 26 } // homePage/oh-package.json5 — 业务模块兼容 API 20+ { "apiType": "stageMode", "minAPIVersion": 20, "targetAPIVersion": 26 } // entry/oh-package.json5 — 入口模块使用最高 API { "apiType": "stageMode", "minAPIVersion": 20, "targetAPIVersion": 26, "compatibleSdkVersion": 20 // 兼容模式 }compatibleSdkVersion是 API 26 新增的配置项。设置为 20 意味着应用在 API 26 设备上运行时会启用兼容模式，使用新的运行时但限制部分新 API 的使用。
五、迁移优先级排序
5.1 各模块评估
| 模块 | 依赖层级 | 迁移工作量 | 影响面 | 优先级 |
|---|---|---|---|---|
| commonLib | 0（最底层） | 中 | 所有模块 | P0 |
| EntryAbility | 1 | 中 | 入口 | P0 |
| homePage | 2 | 大 | 主要 UI | P1 |
| minePage | 2 | 中 | 个人中心 | P1 |
| topicPage | 2 | 大 | 专题学习 | P2 |
| base_select | 1 | 小 | 通用组件 | P1 |
| select_category | 1 | 小 | 分类组件 | P2 |
| answer_questions | 1 | 中 | 答题 | P2 |
| AudioPlayer | 1（commonLib 内） | 小 | 语音播放 | P1 |
| Aggregated Payment | 2 | 小 | 支付 | P3 |
| feedback/search | 2 | 小 | 辅助功能 | P3 |
5.2 核心组件 commonLib 优先升级
commonLib 是所有其他模块的依赖，必须最先完成迁移。包含的迁移项：
- 数据模型：
WordCard、LearningPlan、StatisticsData改用@ObservedV2+@Trace - 工具类：
PreferenceUtil、Logger、RouterModule替换废弃 API - 管理器：
LearningPlanManager、StatisticsManager、NewWordManager保持接口不变
六、迁移后回归测试方案
6.1 测试策略
迁移完成后，需要回归测试覆盖以下维度：
| 测试维度 | 测试内容 | 工具/方法 |
|---|---|---|
| 编译测试 | 所有模块编译通过 | hvigor assemble |
| 功能测试 | 10 个核心功能页面正常 | 手动 E2E + LocalUnit |
| 性能测试 | 启动时间、列表滑动、动画帧率 | HiProfiler |
| 兼容性测试 | API 20/21/23/26 四档版本 | 虚拟机/真机矩阵 |
| 存储测试 | Preferences 数据读写正确 | 自动测试 |
6.2 分阶段回归流程
Phase 1: commonLib + AudioPlayer 迁移 → 编译通过 + 单元测试 Phase 2: EntryAbility + 三个 features 模块 → 编译通过 + 功能测试 Phase 3: 全部 components 模块 → 编译通过 + 功能测试 Phase 4: 全量回归测试 + 性能测试 Phase 5: 新特性接入（ContainerReader、Live View 等） Phase 6: 废弃 API 清理每个阶段预计耗时 2-3 天，总计约 15 个工作日完成全量迁移。
七、"先编译通过→新特性接入→废弃 API 替换"三步策略
第一步：先编译通过
目标是让项目在新 API 版本下编译通过，不做任何优化和新特性接入：
- 更新
oh-package.json5中的targetAPIVersion为 26 - 修复编译错误（主要是废弃 API 和类型变化）
- 使用
@SuppressDeprecation临时屏蔽废弃警告 - 确保所有模块编译通过，应用可以正常运行
第二步：新特性接入
编译通过后，逐步接入新版本的特有能力：
- ContainerReader 替换全局 BreakpointModel
- @ReusableV2 增加组件复用池
- systemMaterial 替换自定义毛玻璃效果
- Live View 实况窗增加锁屏学习进度
第三步：废弃 API 替换
最后清理所有废弃 API：
- 移除
@SuppressDeprecation注解 - 将临时保留的旧 API 全部替换
- 清理兼容层代码
- 最终确认无任何 Deprecation 警告
八、总结
从 API 12 到 API 26 的迁移是一项系统工程，涉及 11 个模块、数十个 API 变更点。通过"commonLib 优先、按模块分批、三步递进"的策略，我们可以在保证应用稳定性的前提下平滑地完成升级。迁移完成后，英语学习 App 将获得方舟引擎性能提升、星盾安全增强、AgentCard 桌面入口、端侧大模型等 7.0 新特性的全面赋能。
