👋 你好，欢迎来到我的博客！我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者，正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来，也为了和更多同路人互相启发，我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向：ArkTS 语言基础、HarmonyOS 原生应用（Stage 模型、UIAbility/ServiceAbility）、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战，以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏：从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘，让每篇都有可落地的代码与方法论。
  💡 我相信：写作是把知识内化的过程，分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长，欢迎关注我，一起交流进步！🚀

前言

把一个已经存在的 HarmonyOS 工程升级到 HarmonyOS 7，最容易产生的误解，是把“升级”理解成修改 targetSdkVersion。

实际上，华为针对 26.0.0 给出的官方升级流程并不是这样。官方明确将升级拆成开发工具链升级、API 变化评估与适配、新旧版本设备兼容验证，以及完成验证后发布应用几个阶段。HarmonyOS 7.0 对应的 API 版本为 26.0.0，而且从 26.0.0 开始，HarmonyOS 开发套件的 API 版本号开始采用 X.Y.Z 形式的语义化版本。

这篇文章就围绕一个很具体的场景展开：

一个仍然面向旧 API 设备运行的存量 Stage 模型应用，需要迁移到 26.0.0 开发套件，同时继续兼容原来的最低系统版本。

真正需要解决的问题不是“怎样把数字改成 26.0.0”，而是怎样确认 哪些东西因为这次升级发生了变化。

一、先分清 HarmonyOS 7、26.0.0 和 targetSdkVersion

官方《应用升级适配指导——向26.0.0升级》已经明确给出对应关系：HarmonyOS 7.0 对应 API 版本 26.0.0。

这里还有一个容易混淆的变化。

26.0.0 以前，HarmonyOS API 版本采用类似：

6.0.0(20)
6.0.1(21)
6.1.1(24)

这样的格式。

从 26.0.0 开始，HarmonyOS 开发套件版本采用语义化版本：

26.0.0

其中主版本、次版本和修订版本分别用于体现不同级别的变化。官方同时提醒：API 版本号格式变化后，应用中涉及 API 兼容性判断的代码也需要关注相应兼容性说明。

这也意味着迁移时至少要分清三个概念：

配置迁移时应该怎么理解
compileSdkVersion当前使用哪一版 SDK 编译
compatibleSdkVersion应用准备兼容到的最低 SDK 版本
targetSdkVersion应用面向哪个目标 SDK 行为运行

其中最需要警惕的是 targetSdkVersion。

官方 26.0.0 升级指导指出：某些 API 行为变化可以通过 targetSdkVersion 进行隔离，以提供向前兼容处理。也就是说，targetSdkVersion 不只是一个“我已经升级”的版本标签，它可能直接影响运行时采用哪套行为。

所以，不建议把它作为迁移工作的第一步。

二、为什么升级前必须先看变更说明

升级开发套件以后，代码能否重新编译只解决了一部分问题。

HarmonyOS 版本演进过程中可能出现：

  • 新增 API；
  • API 废弃；
  • API 删除；
  • 参数或返回类型变化；
  • 错误码变化；
  • 权限或使用范围变化；
  • 运行时行为变化。

26.0.0 的官方 API Change List 就按照 Kit 提供了这些变化。比如 Notification Kit 的 26.0.0 变更中，notificationManager.isDistributedEnabled() 被标记为从 26.0.0 开始废弃；同一批变更里，notificationManager.publish() 还增加了错误码。

ArkUI 的变更清单则能看到另一类情况：除了新增接口和可选属性，还有删除 API、函数参数类型调整、错误码删除等变化。例如 26.0.0 的 ArkUI API Change List 中列出了部分 Symbol 相关类型删除，以及 SymbolGlyphAttribute.shaderStyle() 参数定义调整。

这正是为什么升级不能按照：

修改版本号
↓
解决编译错误
↓
打包

这样的流程做。

更合理的思路应该是：

确认版本跨度
↓
升级开发工具链
↓
扫描当前工程实际使用的 API
↓
核对新增 / 废弃 / 删除 / 行为变化
↓
修改代码
↓
编译与静态问题清理
↓
旧系统 + 新系统验证
↓
再调整并确认目标 SDK 配置
↓
发布

三、第一步先升级开发套件，而不是改工程目标版本

官方针对 26.0.0 的指导要求先取得与最新 HarmonyOS 开发套件对应的 DevEco Studio。

如果已经安装旧版 DevEco Studio，可以通过 IDE 检查更新，也可以从官方页面获取新版。升级以后还应该阅读跨越版本对应的 DevEco Studio Changelog。

这里还有一个对 CI 环境很重要的细节。

从 6.0.0(20) 开始，DevEco Studio 已经预置对应版本 HarmonyOS SDK；如果工程还有命令行构建流水线，官方建议同步升级对应版本的命令行工具，避免 IDE 和 CI 使用两套不同 SDK 构建同一个工程。

因此一个存量项目可以先做这样的检查：

本地 DevEco Studio
        │
        ├── HarmonyOS SDK
        │
CI / Jenkins / 自建流水线
        │
        └── Command Line Tools + HarmonyOS SDK

两边不要只升级一边。

否则开发机已经基于 26.0.0 SDK 编译，而流水线仍然使用旧版本工具链，后面排查“本地正常、CI 失败”会复杂很多。

四、一个很关键的细节：targetSdkVersion 没写时也不能掉以轻心

这是这次升级里非常值得单独强调的一点。

华为 26.0.0 官方升级指南明确说明：

升级 DevEco Studio 后，如果工程没有显式配置 targetSdkVersion，该字段会自动更新到与新版 DevEco Studio 匹配的 SDK 版本；默认用于构建的 compileSdkVersion 也会升级到对应版本。

所以，“我没有修改 targetSdkVersion”并不必然等于“目标版本没有变化”。

迁移前应该把工程现状记录下来。

以一个原本面向 5.0.5(17) 的存量工程为例，项目级 build-profile.json5 中相关配置可能类似下面这样。这里的结构和字段均来自华为官方构建配置示例；具体旧版本值应以自己的现有工程为准。

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.5(17)",
        "targetSdkVersion": "5.0.5(17)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

这一步的目的不是要求所有工程都使用 5.0.5(17)，而是在升级之前记录原来的最低兼容版本和目标版本。

如果原来是 18、20、23 或 24，就保留自己的实际值。

五、用 API Change Assistant 找真正受影响的代码

手工阅读所有 Kit 的 API Change List 对大型工程并不现实。

DevEco Studio 提供的 API Change Assistant 正适合处理这个问题。

根据 26.0.0 官方升级指导，它可以检查当前项目中使用的 ArkTS API 和 C API 是否在指定 SDK 版本区间发生行为变化，并把结果关联回代码位置和官方适配说明。

入口是：

Tools
└── API Change Assistant

进入后：

选择旧 SDK 版本
        ↓
选择目标 SDK 版本
        ↓
Start Scan
        ↓
检查扫描结果
        ↓
根据 Code Location 回到代码
        ↓
通过 Guidance link 打开对应官方变更说明

这里真正有价值的并不是“扫描出了多少条”，而是把每一条变化分成不同处理方式。

可以给扫描结果建立这样一张迁移表：

类型处理方式
新增 API只有需要使用新能力时才接入，同时检查旧系统兼容
Deprecated找官方推荐替代方案，规划迁移
删除 API必须修改调用代码
参数/返回值变化检查类型及业务处理
错误码变化检查异常分支
行为变化重点核对 targetSdkVersion 隔离规则
权限变化重新核对权限声明和申请逻辑

扫描完成后，API Change Assistant 还支持导出结果，适合把它直接作为迁移任务清单。官方也说明，大型工程如果扫描较慢，可以在工具设置中调整最大堆内存。

六、新增、废弃和行为变化，处理方式完全不同

这里比较容易出现一个理解偏差：看到 API Change Assistant 报出一条变化，就直接“改成新 API”。

实际上需要先判断变化类型。

1. 新增 API

如果一个接口从 26.0.0 才开始提供，而应用的 compatibleSdkVersion 仍然保持在旧版本，那么使用它时就必须考虑旧设备。

官方升级指南专门指出：应用升级后如果使用新版 API，一部分尚未升级系统的设备可能并不支持这些接口，需要额外处理兼容问题。

所以：

compileSdkVersion 足够高

只能说明代码能够看到这个接口，并不等于：

compatibleSdkVersion 对应的所有设备

都能够执行它。

2. Deprecated API

废弃意味着接口仍可能存在，但已经进入迁移阶段。

例如前面提到的 Notification Kit：

notificationManager.isDistributedEnabled()

官方 26.0.0 API Change List 已经将其废弃版本标记为 26.0.0。

这类问题应该通过对应 API Reference 和官方迁移说明进一步确认替代方案，而不是因为“目前还能编译”就忽略。

3. 删除或签名变化

这类问题更容易直接表现为编译错误。

例如 ArkUI 的 26.0.0 API Change List 中已经存在 API 删除以及函数参数类型调整。

修复时应该按照：

编译错误
→ 对照 API Change Assistant
→ 打开对应官方 Guidance
→ 确认旧定义和新定义
→ 修改调用代码

而不是只根据 IDE 自动补全猜一个能编译的写法。

4. 行为变化

这是最容易被漏掉的一类。

代码可能：

没有编译错误

但：

targetSdkVersion 变化

以后运行逻辑已经不同。

官方正因为存在这类变化，才提供基于 targetSdkVersion 的兼容性隔离机制。

所以升级验证不能只以“Build 成功”为结束条件。

七、编译问题应该怎么修

工具链和 SDK 更新以后，建议先执行一次完整构建，把问题分成三类。

第一类：源码 API 错误

例如：

  • 原类型已经删除；
  • 方法参数发生变化；
  • import 对应定义发生变化；
  • C API 接口定义发生变化。

这类问题优先回到 API Change Assistant 和 API Change List。

第二类：构建系统问题

不要只盯 ArkTS。

工程如果带 Native/C++ 模块，还需要检查模块级 build-profile.json5 的 externalNativeOptions。官方文档明确指出，HarmonyOS NDK 工程使用 CMake 和 Ninja 构建 Native 代码，externalNativeOptions 是 C/C++ 构建配置入口。

例如：

{
  "apiType": "stageMode",
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": "",
      "cppFlags": "",
      "abiFilters": [
        "arm64-v8a",
        "x86_64"
      ]
    }
  }
}

如果工程包含 .so、NDK、CMake 或 Native 三方库，升级时应把它们单独列进验证范围。

第三类：依赖问题

官方 26.0.0 升级指南特别提醒，除了 HarmonyOS API，还需要考虑应用使用的 HAR 以及集成态 HSP 的兼容性。

所以看到业务源码已经没有错误，并不能直接认为迁移完成。

依赖检查至少要覆盖：

oh-package.json5
HAR 依赖
HSP
Native SO
构建插件

如果是第三方组件，还应该去对应库的官方 Release/仓库确认其支持的 HarmonyOS SDK 范围。

八、适配完成以后，再决定 targetSdkVersion

API 变化已经处理、代码已经完成一次完整构建之后，才比较适合进入 targetSdkVersion 的收口阶段。

假设原项目是：

{
  "compatibleSdkVersion": "5.0.5(17)",
  "targetSdkVersion": "5.0.5(17)"
}

并且已经完成 26.0.0 行为变化的适配，那么迁移目标可以表达为：

{
  "compatibleSdkVersion": "5.0.5(17)",
  "targetSdkVersion": "26.0.0"
}

真正需要关注的是这两个值为什么可以不同。

compatibleSdkVersion 表示应用准备兼容的最低 SDK 范围；如果业务仍然需要覆盖旧版本设备，就不应该为了“看起来升级彻底”而无依据地一起提高。

华为此前的版本配置指导同样采用这样的原则：已开发应用升级 SDK 时，compatibleSdkVersion 建议保持升级前版本；完成新版变化适配之后，再把 targetSdkVersion 调整到新版。

而对于 26.0.0，具体还应以当前版本升级指南及扫描出的行为变化为准。

换句话说，这次升级不是：

old targetSdkVersion
        ↓
26.0.0

而是：

旧工程
  ↓
26.0.0 工具链
  ↓
API Change Assistant
  ↓
API / 行为 / 依赖适配
  ↓
完整编译
  ↓
调整 targetSdkVersion
  ↓
重新验证

九、新系统能跑还不够，旧系统也必须重新验证

官方 26.0.0 升级指南要求：应用使用新 SDK 编译完成后，需要同时安装到旧版本和新版本设备进行完整功能验证。

这是整个迁移过程中不能省掉的一步。

可以建立一个最小测试矩阵：

环境重点验证
原最低兼容 API 附近设备新版编译产物是否仍然可安装、核心功能是否正常
中间版本设备跨版本行为是否存在差异
HarmonyOS 7 / API 26新目标版本行为、UI、权限和主要业务
不同设备形态如果应用声明支持，应覆盖 Phone、Tablet、PC/2in1 等对应设备

其中安装失败时，一个非常实用的排查点是 compatibleSdkVersion。

华为官方 FAQ 给出的案例中，如果 HAP 安装时报：

compatibleSdkVersion and releaseType of the app
do not match the apiVersion and releaseType on the device

应先检查设备 API 版本和工程的 compatibleSdkVersion 是否匹配。

设备 API 版本可通过：

hdc shell param get const.ohos.apiversion

查询。

这个命令很适合加入升级后的兼容测试记录中：

设备型号：
系统版本：
设备 API：
安装结果：
启动结果：
核心页面：
权限流程：
关键业务：
异常日志：

如果本地没有足够多的旧版本设备，官方升级指南建议使用 AppGallery Connect 云调试。AGC 官方资料也提供了 HarmonyOS 云端设备调试入口。

十、为什么“只修编译错误”仍然不够

整个迁移过程里，编译器只能帮我们发现一部分问题。

假设某段代码没有任何语法错误：

Build Success

最多证明：

当前代码可以由当前工具链完成构建

它不能自动证明：

旧 API 设备一定正常
新版 targetSdkVersion 行为一定正确
HAR/HSP 一定兼容
权限流程一定没有改变
所有异常码仍按旧逻辑工作

这也是官方升级指导为什么要把“API 变化评估”和“新旧系统验证”分别作为独立阶段。

这个地方特别适合形成一条开发习惯：

编译问题看编译器，版本问题看 Release Notes 和 API Change List，运行时兼容问题看目标版本行为并上设备验证。

三类问题不要混在一起。

十一、几个特别容易出问题的地方

1. 直接删除旧 targetSdkVersion

如果工程本来显式配置了旧值，直接删除配置并升级 DevEco Studio，并不代表“保持原状”。

26.0.0 官方指南明确指出，在没有显式配置时，targetSdkVersion 会随新版开发套件更新。

因此迁移之前应该先记录旧配置。

2. 把 compileSdkVersion 和 compatibleSdkVersion 当成一个东西

用 26.0.0 SDK 编译，不代表应用最低系统版本必须同时提升到 26.0.0。

是否提高 compatibleSdkVersion 应由产品实际支持范围以及使用的 API 决定。

3. 只检查 ArkTS，不检查 Native

API Change Assistant 能检查 ArkTS API 和 C API 的行为变化。带 Native 模块的工程不要只处理 .ets 文件。

4. 只处理 Deprecated，不处理行为变化

Deprecated 很显眼，因为 IDE 或变更清单容易看到。

真正危险的是代码继续编译，但新版目标 SDK 下行为改变。

5. 忽略 HAR 和 HSP

官方升级指南已经明确把第三方 HAR 和集成态 HSP 放进兼容性考虑范围。

尤其是存量工程，依赖往往比业务代码更早暴露版本问题。

十二、实际项目可以按这个顺序排查

对于从旧 API 向 26.0.0 迁移的工程，可以把排查顺序固定下来：

  1. 记录升级前版本配置
    保存原 compatibleSdkVersion、targetSdkVersion、工具链和依赖版本。

  2. 确认目标版本
    HarmonyOS 7 对应 API 26.0.0，不要混用旧版本编号体系。

  3. 升级 DevEco Studio 与命令行工具
    CI 和本地工具链保持一致。

  4. 运行 API Change Assistant
    按实际升级跨度扫描 ArkTS / C API。

  5. 逐项核对官方 API Change List
    分清新增、废弃、删除、签名变化、错误码变化和行为变化。

  6. 检查 HAR、HSP 和 Native 模块
    不要只看 entry 中的 ArkTS 代码。

  7. 解决完整构建问题

  8. 完成新版行为适配后再确认 targetSdkVersion

  9. 在旧系统和 API 26 环境分别验证

  10. 检查 release 包和签名

  11. 再进入 AppGallery Connect 发布流程

这套顺序的核心并不复杂：先知道发生了什么变化，再决定版本配置应该怎么变。

十三、验证完成，再提交应用市场

华为 26.0.0 升级指导把“发布最新编译应用到 AppGallery”放在兼容验证之后，而不是编译完成之后。

AppGallery 官方发布流程要求先上传应用软件包，软件包通过基础合法性检测后才能用于版本发布；正式发布还需要填写应用信息、分发信息和隐私声明，并满足应用市场审核要求。

对于一次 API 26 升级，提交前至少建议重新检查：

□ release 模式可以完整构建
□ release 包签名正确
□ compatibleSdkVersion 符合实际最低支持范围
□ targetSdkVersion 与本次适配结果一致
□ API Change Assistant 扫描项已经处理
□ Deprecated / Deleted API 已确认
□ 行为变化已经验证
□ HAR / HSP / Native 依赖已检查
□ 旧版本设备核心流程完成验证
□ HarmonyOS 7 / API 26 完成验证
□ 权限与隐私声明与当前版本实际行为一致

如果上传阶段出现签名问题，也应该回到签名链路处理，而不是继续修改 API 配置。华为官方已经专门整理了构建及上传场景下的签名错误，例如包名和 SigningConfigs 不匹配、上传包未签名等情况。

开发经验总结

从旧 API 升到 HarmonyOS 7 / API 26，真正需要控制的是“变化”，而不是版本号本身。

可以把整个迁移压缩成四句话。

第一，HarmonyOS 7 对应 API 26.0.0，而且 26.0.0 开始采用新的语义化 API 版本格式。

第二，不要把修改 targetSdkVersion 当成升级起点。 官方已经明确说明，一部分行为变化可能以它作为兼容隔离条件，而且没有显式配置时，升级开发套件后它还可能随 SDK 一起更新。

第三，先让 API Change Assistant 告诉我们工程真正涉及哪些变化。 新增、Deprecated、删除、签名变化、错误码变化和行为变化，需要采用不同处理策略。

第四，新 SDK 编译成功不等于兼容完成。 用 26.0.0 SDK 得到新的构建产物后，还必须回到旧系统验证一次，再在 HarmonyOS 7/API 26 上验证一次，确认支持范围之后才适合进入应用市场发布。

如果正在维护一个已经迭代多年的 HarmonyOS 工程，不妨先打开一次 API Change Assistant。迁移到 API 26 时，最值得优先弄清楚的通常不是“有多少编译错误”，而是：工程里到底有多少 API 的运行规则已经发生变化。

📝 写在最后

如果你觉得这篇文章对你有帮助，或者有任何想法、建议，欢迎在评论区留言交流！你的每一个点赞 👍、收藏 ⭐、关注 ❤️，都是我持续更新的最大动力！

我是一个在代码世界里不断摸索的小码农，愿我们都能在成长的路上越走越远，越学越强！

感谢你的阅读，我们下篇文章再见～👋

✍️ 作者：菜鸟不学编程
🧵 本文原创，转载请注明出处。

# harmonyos # 鸿蒙
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

到公司自动触发签到提醒：Location Kit 地理围栏实践【鸿蒙心迹】

avatar 人工智能6S服务平台

Redis 主库宕机 7.4 秒：鸿蒙任务接续服务的哨兵实战鸿蒙HarmonyOSRedis

系列第 2 篇。上一篇用 4 台云主机搭了鸿蒙多设备任务接续的后端，1 万长连接零丢失，但留了一个单点：Redis。这一篇把它换成主从 + 三哨兵，然后在 1 万连接压测中直接停掉主库，看真实表现。

avatar 人工智能6S服务平台

不装 DevEco Studio：用官方 CLI 把 ArkTS 应用装进鸿蒙云手机，改一版只要 24 秒

工具链hvigorw（编译）+hdc（部署/调试）+ JDK 17，SDK 自带 hdc 不用另外下工程配置两边一致、真实存在、别漏连接稳定性hdc kill→tconn是唯一可靠的复位方式五个坑里，三个是错误信息骗人（说是升级问题其实是配置缺失、说是启动失败其实已启动、说是签名问题其实能装），两个是状态残留（hdc 死连接、ZIP 断包）。这些都不在官方文档里，只能靠踩。希望这篇能让你少踩几个。

avatar 人工智能6S服务平台