前言

现有 HarmonyOS 6 原生项目迁移到 HarmonyOS 7 API 26，如果我们在执行过程中理不清逻辑，就会把问题混在一起。

编译失败、依赖冲突、页面异常、权限失效、数据读取失败、真机安装失败，这些问题如果一起出现，很容易让人误以为是 API 26 本身不稳定。实际迁移时，很多问题来自工程配置、SDK 版本、第三方依赖、签名证书、权限声明、页面路由和数据结构变化。我们只有把这些问题分层记录，迁移工作才不会失控。

HarmonyOS 7 API 26 Developer Beta1 面向开发调测，能够体验 API 26.0.0 Beta1 版本的新能力、新特性，并使用 DevEco Studio 进行应用开发。这个阶段非常适合提前检查工程兼容性，但测试结论不能直接套用到正式版本表现。

所以，迁移工作不要一开始就进入大范围业务改造。更稳的做法，是先做一张兼容性清单。

这张清单至少覆盖五类内容。

• 版本基线
• 工程配置
• 编译构建
• 运行链路
• 业务主流程

如果你手里已经有一个 HarmonyOS 6 项目，比如会议随记、待办工具、本地生活助手、资料整理工具，第一轮迁移目标应该是：先让项目在 API 26 环境下能够编译、安装、启动、运行主流程，再判断哪些 HarmonyOS 7 新能力值得接入。

一、先冻结迁移基线

迁移现有项目之前，第一步不是修改代码，而是冻结基线。

这里的基线包括当前项目状态、当前分支、当前 DevEco Studio 版本、当前 HarmonyOS SDK 版本、当前测试设备、当前主流程是否稳定。只要这些信息没有记录清楚，后续任何一个问题都很难复查。

对于已经能在 HarmonyOS 6 上正常运行的项目，建议先创建一个独立迁移分支。

main
  └── migration/api26-beta

主分支继续保持稳定，API 26 相关调整都进入迁移分支。后续如果某个配置改坏了，仍然可以回到原来的 HarmonyOS 6 状态对照。

迁移基线可以先记录这些内容。

检查项	记录内容	作用
项目分支	migration/api26-beta	避免影响主线代码
原始版本	当前 HarmonyOS 6 工程状态	便于回滚和对比
DevEco Studio	当前安装版本	判断工具链问题
HarmonyOS SDK	当前 SDK 版本	判断 API 版本问题
测试设备	设备型号和系统版本	判断设备侧问题
主流程状态	迁移前是否正常	判断问题是否迁移引入
依赖清单	HAR、ohpm、第三方库	判断依赖冲突
签名配置	调试签名和发布签名	判断安装问题

这里大家很容易忽略 迁移前主流程状态。比如会议列表是否正常加载、会议详情是否正常打开、联系人是否正常读取、待办是否能够创建。如果迁移前没有做一次基线确认，迁移后出现问题时，很难判断它是新版本引入的，还是原来项目里已经存在的边界问题。

我们可以先给项目做一个迁移前快照。

主流程	迁移前状态	备注
应用启动	正常 / 异常	保存截图和日志
首页加载	正常 / 异常	记录首屏耗时
列表读取	正常 / 异常	记录数据来源
详情跳转	正常 / 异常	记录路由参数
新建保存	正常 / 异常	记录数据库写入
权限申请	正常 / 异常	记录授权弹窗
设置页面	正常 / 异常	记录本地配置

这张表看起来很基础，但它能把迁移工作从 边改边猜 拉回到 对照验证。迁移过程中出现异常时，先对照基线，再判断问题来源。

二、先检查 SDK 版本和工程配置

基线冻结以后，第二步是检查 SDK 版本和工程配置。

HarmonyOS 工程里，版本配置非常关键。应用兼容性相关文档中明确了 compatibleSdkVersion、targetSdkVersion、compileSdkVersion 三者之间的关系：compatibleSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion。如果配置不符合规则，工程就会出现报错。

这里我们先把三个概念放清楚。

配置项	作用	迁移时要关注什么
compileSdkVersion	编译时使用的 SDK 版本	是否切到 API 26 对应 SDK
targetSdkVersion	应用目标适配的 SDK 版本	是否准备面向 API 26 行为验证
compatibleSdkVersion	应用兼容的最低 SDK 版本	是否仍然覆盖目标设备范围

如果你只是想检查项目能否在 API 26 环境中编译，第一轮可以先处理 compileSdkVersion 和工具链匹配问题。如果要进一步验证 API 26 行为，就要认真检查 targetSdkVersion。如果项目还需要覆盖 HarmonyOS 6 设备，则不能随意提高 compatibleSdkVersion，否则可能影响安装范围。

这里我建议准备一张配置检查表。

检查项	当前值	API 26 迁移建议	备注
compileSdkVersion	待填写	对齐 API 26 SDK	先验证编译
targetSdkVersion	待填写	分阶段调整	涉及行为变化
compatibleSdkVersion	待填写	谨慎调整	影响最低兼容范围
releaseType	待填写	记录 Beta / Release	影响环境判断
module 配置	待填写	检查权限和入口	影响安装运行
oh-package 依赖	待填写	检查版本冲突	影响编译构建
hvigor 配置	待填写	检查构建链路	影响打包产物

这一步大家不要急着一次性把所有版本都调到最高。对存量项目来说，更稳的策略是分阶段处理。

第一阶段只确认工程能在 API 26 环境中打开和编译。
第二阶段确认主流程能在测试设备上运行。
第三阶段再接入 HarmonyOS 7 新能力。
第四阶段再考虑是否调整更高目标适配策略。

这个顺序可以降低风险。因为 SDK 版本、工程配置、项目代码、新能力接入如果同时变化，后面出错时很难定位。

工程配置可以用一段示意结构辅助说明。这里的片段属于项目配置草案，不代表某个具体项目的最终配置。

{
  "compileSdkVersion": 26,
  "targetSdkVersion": 26,
  "compatibleSdkVersion": 18
}

这段配置的意义，是提醒版本关系要满足约束。真实项目里，具体数值要结合当前 SDK、目标设备、项目兼容范围和实际构建要求确认。不要直接复制示意值到生产项目里。

如果项目依赖第三方 HAR 包，还要继续检查依赖兼容性。应用配置的 compatibleSdkVersion 需要满足依赖库要求，否则构建可能失败。

三、再把编译构建和依赖问题单独拆开

SDK 和工程配置检查完以后，第三步就是编译构建。

迁移到 API 26 的第一轮编译，不建议顺手改业务逻辑。先保持代码尽量不变，只看项目在新工具链下能不能通过构建。这样才能判断问题到底来自配置、依赖、API 变化，还是业务代码本身。

编译失败时，可以先把错误分成几类。

错误类型	常见表现	优先排查方向
SDK 配置错误	版本不匹配、SDK 找不到	SDK 安装和项目配置
依赖冲突	HAR、ohpm 包版本不兼容	依赖版本和 compatible 要求
类型错误	ArkTS 类型检查失败	代码类型和接口定义
API 缺失	import 失败、符号不存在	API 版本和 Kit 状态
构建插件错误	hvigor、构建任务失败	构建配置和插件版本
资源错误	资源路径、图片、配置文件异常	资源目录和命名

这个分类很重要。因为如果所有编译错误都放在一起处理，很容易越改越乱。比如 import 失败可能是新 API 不存在，也可能是 SDK 没有切到目标版本，还可能是模块没有正确引用。先分类，再定位，迁移节奏会稳很多。

我们可以准备一个构建错误记录表。

错误编号	错误类型	文件位置	错误信息	初步判断	处理状态
001	SDK 配置	build-profile	待填写	SDK 版本不匹配	待处理
002	依赖冲突	oh-package	待填写	第三方库版本问题	待处理
003	API 缺失	某页面文件	待填写	新 API 状态待确认	待处理
004	类型错误	service 文件	待填写	ArkTS 类型收紧	待处理

如果使用 DevEco Code 或其他工具解释编译错误，也建议把工具建议和最终构建结果分开记录。工具建议只能作为排查线索，真正的结论仍然要看重新编译结果。

可以用这样的记录结构。

{
  "errorType": "dependency-conflict",
  "file": "oh-package.json5",
  "symptom": "构建阶段出现依赖版本冲突",
  "suggestion": "检查 HAR 包兼容版本",
  "changeScope": "仅调整依赖版本",
  "buildResult": "pending"
}

这类模板不复杂，但可以帮助你把一次迁移排查变成可复查记录。后续如果同类错误再次出现，就不需要重新从头分析。

四、继续验证运行链路、权限和数据兼容

项目编译通过之后，我们还不能马上判断迁移完成。

编译通过只说明代码能在当前工具链下构建，真正的兼容性还要看运行链路。应用能不能安装、能不能启动、首页能不能加载、页面能不能跳转、权限能不能正常申请、数据能不能正常读取，这些都要单独验证。

建议先验证一条最小运行链路。

安装应用 → 启动应用 → 首页加载 → 列表读取 → 详情跳转 → 新建保存 → 返回刷新

对于会议类应用，我们可以这样拆。

运行节点	验证目标	常见问题
安装应用	HAP 能否安装到设备	签名、包名、设备版本
启动应用	应用能否正常打开	白屏、崩溃、入口异常
首页加载	工作台是否显示	数据为空、状态异常
列表读取	会议列表是否正常	数据库读取失败
详情跳转	页面参数是否正常	路由参数丢失
新建保存	表单保存是否正常	数据写入失败
返回刷新	列表状态是否更新	状态管理异常

这个链路覆盖了大多数存量项目迁移时的核心问题。只要这条链路不稳定，就不要急着接入 HarmonyOS 7 新能力。

权限也是迁移时容易出问题的位置。录音、文件、通知、联系人、相册、网络这些权限，迁移后都应该重新走一遍授权链路。尤其是涉及 API 26 新能力时，权限可能还要继续检查文档和设备条件。

这里可以准备一张权限检查表。

权限场景	验证内容	当前状态
录音	是否触发授权，录音是否可用	待验证
文件	是否能读取和保存文件	待验证
通知	是否能发送提醒	待验证
联系人	是否能读取或关联联系人	待验证
网络	是否能访问服务接口	待验证
相册	是否能选择图片或保存图片	待验证

数据兼容也要单独处理。HarmonyOS 6 项目里已经存在本地数据库、缓存、用户配置和历史记录时，迁移到 API 26 环境后，不能只看新建数据是否正常，还要看旧数据能不能读取。

可以这样检查。

数据类型	迁移风险	验证方式
本地数据库	表结构变化、字段缺失	使用旧数据启动应用
用户配置	默认值变化、读取失败	检查设置项是否保留
缓存数据	路径变化、格式变化	清理和保留两种状态都验证
文件路径	文件访问权限变化	验证录音、图片、附件路径
业务记录	历史会议、待办、联系人	使用真实数据样本验证

如果没有真实用户数据，可以准备一份模拟旧数据。它不需要很复杂，但要覆盖关键字段。比如会议标题、开始时间、参与人、录音路径、纪要文本、待办列表。这样你才能判断迁移后的读取逻辑是否正常。

我们的重点是：编译通过以后，继续验证主流程和旧数据。

很多迁移问题都不是编译阶段出现，而是在运行阶段才暴露出来。比如页面能打开，但详情没有数据；表单能保存，但返回列表没有刷新；权限弹窗出现了，但拒绝授权后没有回退。只有把这些场景跑一遍，才能判断项目是否真正具备 API 26 迁移基础。

五、最后把兼容性清单变成处理优先级

迁移过程中收集到的问题，最后一定要变成优先级。

如果只是把问题记录下来，不做优先级排序，项目很容易陷入 每个问题都很重要 的状态。迁移项目最需要先保证的是主流程能运行，其次是核心功能可用，再往后才是新能力接入、视觉优化和体验增强。

可以先把迁移问题分成 P0、P1、P2 三类。

优先级	问题类型	处理原则
P0	无法编译、无法安装、无法启动、主流程崩溃	立即处理
P1	核心功能异常、权限异常、数据读取异常	优先处理
P2	视觉问题、低频页面异常、体验优化、新能力接入	排期处理

对于会议类应用，可以这样整理。

模块	问题	优先级	处理建议
工程构建	API 26 下编译失败	P0	先修复构建链路
应用启动	启动白屏或崩溃	P0	查看入口和日志
会议列表	历史会议无法读取	P1	检查数据库和旧数据
会议详情	路由参数丢失	P1	检查页面跳转参数
新建会议	保存后不刷新	P1	检查状态管理
设置页	某个开关样式异常	P2	后续体验优化
AI 能力	纪要生成未接入	P2	等主流程稳定后验证

这个优先级会帮助你控制节奏。P0 没有解决之前，不建议接 HarmonyOS 7 新能力。P1 没有稳定之前，不建议大范围改页面。P2 可以排期，不需要阻塞迁移主线。

最后我我们就形成了一张完整的 API 26 兼容性清单。

分类	检查项	当前状态	下一步
版本基线	DevEco Studio、SDK、设备版本	待填写	记录版本信息
工程配置	compile、target、compatible	待填写	检查版本关系
编译构建	SDK、依赖、类型、资源	待填写	保存错误日志
安装启动	签名、包名、设备版本	待填写	验证真机安装
主流程	首页、列表、详情、新建、刷新	待填写	跑通核心链路
权限能力	录音、文件、通知、联系人	待填写	重新验证授权
数据兼容	数据库、缓存、文件路径	待填写	使用旧数据验证
新能力	Skill、Agent、AI、工具链	待填写	等主流程稳定后进入

总结

现有 HarmonyOS 6 项目迁移到 API 26，不适合一开始就重构主流程，也不适合马上接入所有新能力。

更稳妥的方式，是先做一张如下的兼容性清单。

步骤	要做什么
1	冻结迁移基线
2	检查 SDK 版本和工程配置
3	拆分编译构建和依赖问题
4	验证运行链路、权限和数据兼容
5	把问题转成 P0、P1、P2 优先级

以会议随记类应用举例，第一轮迁移可以先关注：能不能编译、能不能安装、首页能不能加载、会议列表能不能读取、会议详情能不能跳转、新建会议能不能保存、历史数据能不能正常读取。

等这些问题稳定以后，我们再进入 HarmonyOS 7 的 Skill、Agent、AI 开放能力和 DevEco 工具链验证。