【跨端】HarmonyOS 跨端工程实践 01|API 26、Flutter 与 uni-app x 版本兼容性管理【鸿蒙心迹】
一套应用在 Android 和 iOS 上跑了几年,突然要加一个 HarmonyOS 版本,很多团队的第一反应是“把工程编译出来”。我更愿意把第一件事改成:先写清楚我们准备让哪一套代码、哪一个框架分支、哪组构建工具在什么设备上运行。
这件事听起来不如写 UI 有成就感,却能决定后面几周是有序适配,还是每天在新旧版本之间来回切换。
本文从“随行清单”这个小应用展开。它有三组数据:出行准备清单、工作安排和生活事项;页面不复杂,恰好适合把版本问题暴露得足够清楚。我们准备让同一套业务规则分别在 Flutter for OpenHarmony 和 uni-app x 上落地,最终面向 HarmonyOS 7 / API 26 做适配验证。
这次先不追求谁跑得更快,也不急着断言哪套框架更合适。第一步只做一份能被团队共同使用的版本兼容矩阵:什么是官方已公布的能力,什么是框架社区的支持范围,什么必须靠我们自己的构建、运行和回归来确认。

一、版本不是一个数字,是一整条依赖链
HarmonyOS 7 的配套 API 版本为 26.0.0。从这一版本起,HarmonyOS 开发套件采用 X.Y.Z 形式表示 API 版本,而不是只写“API 26”就能概括全部配套关系。官方升级指导还提醒开发者对比 API 行为变化,并在新旧设备上做兼容回归。也就是说,系统 API 升级不等于框架自动完成了全部适配。
团队里经常会出现这样的讨论:
“Flutter 版本已经够新了,应该就能支持 HarmonyOS 7 吧?”
问题是,Flutter 原生社区版本、Flutter for OpenHarmony 分支、Engine、三方插件、宿主 ArkTS 工程并不是同一件事。Flutter 页面绘制成功,也不能直接推导出文件、媒体、通知和生命周期都正确。uni-app x 同理:HBuilderX 能编译出应用,只能说明起点成立;插件、设备 API、UTS 调用和实际业务页面仍然需要逐项验证。
因此,我把版本分成五个层面记录:
| 层面 | Flutter 路线要锁定什么 | uni-app x 路线要锁定什么 |
|---|---|---|
| 系统与 SDK | HarmonyOS API 26.0.0、设备实际 API 版本 | HarmonyOS API 26.0.0、设备实际 API 版本 |
| 框架 | CPF-Flutter 适配分支及提交/Release 标签 | HBuilderX 版本及内置 uni-app x 运行时 |
| 构建 | DevEco Studio、Hvigor、ohpm、Node.js、Dart | HBuilderX、DevEco Studio、Hvigor、ohpm、Node.js |
| 原生接入 | OHOS Engine、Platform Channel、插件版本 | UTS 插件、ArkTS 接口、原生模块依赖 |
| 发布与验证 | 签名、包结构、功能回归、目标设备 | 签名、包结构、功能回归、目标设备 |
不要只在版本表上打一个“支持”勾。 真正能进入项目验收的判断,至少要有环境、步骤、产物和复核人。
可以在 DevEco Studio 中核对工程与本机工具链配置,为兼容性验证记录环境信息。

二、先对齐公开版本,再决定工程基线
截至 2026 年 11 月,华为已推荐使用 HarmonyOS SDK / DevEco Studio 26.0.0 Release 作为正式开发基线;官方版本列表也列出了 26.0.1 Beta1。针对准备交付的团队,我建议正式构建先锁定已经发布的稳定工具链,Beta 分支只在单独实验分支验证新能力,不要因为版本号更大就直接切主线。
Flutter 方面,华为开发指导列出了已经完成鸿蒙平台适配的 Flutter 版本,包括 3.7.12、3.22.0、3.27.4、3.35.7 和 3.41.9。CPF-Flutter 仓库进一步列出了带 +ohos-... 后缀的产物标签。举例来说,公开仓库中可找到 3.41.9+ohos-1.0.2 之类的适配发行物。这些信息说明“有可选分支”,不代表任意上游 Flutter 3.41.9 安装包都自带 OHOS 支持。
uni-app x 的官方鸿蒙开发指南给出的起点是 HBuilderX 4.61+,并说明其代码可编译到 ArkTS 引擎上。这里同样要特别注意:这只是鸿蒙平台支持的起始门槛,不是“4.61 在 API 26 上所有功能均已验证”的承诺。HBuilderX 的实际发行版、运行模式和插件兼容说明需要跟随你使用的版本一起核对。
我最终让“随行清单”采用下面的候选组合作为首轮验证对象:
| 项目 | 候选基线 | 当前判断 | 需要补的证据 |
|---|---|---|---|
| HarmonyOS SDK | 26.0.0 Release | 官方推荐 | 构建机和设备 API 截图 |
| DevEco Studio | 26.0.0 Release 配套版 | 官方推荐 | About / SDK 信息 |
| Flutter OH | CPF-Flutter 3.41.9 系列稳定产物 | 社区适配版本可用 | 锁定具体标签、Engine 与插件 |
| uni-app x | HBuilderX 4.61+ 的受支持发行版 | 官方已有鸿蒙开发路线 | 锁定运行时模式、HBuilderX 精确版本 |
| 目标设备 | HarmonyOS 7 / API 26 | 待项目运行验证 | 安装、启动、权限、行为回归 |
这里刻意没有填写“全部通过”。一张表如果早早填满绿色,对项目并没有帮助;能明确区分已知支持与项目待测,才算真正在做兼容管理。
三、在装框架之前,先给构建机做一次体检
我会把构建机检查放在真正创建工程之前,至少把命令输出存档:
# Flutter 路线:必须由已经配置好的 OpenHarmony 适配 SDK 执行
flutter --version
flutter doctor -v
dart --version
flutter devices
# HarmonyOS 工具链:在对应工具的终端环境执行
hdc version
node --version
ohpm --version
Flutter 的执行路径尤其要检查。有一次同事明明切到了 OHOS 分支,终端却先找到另一套上游 Flutter SDK,flutter --version 看起来是对的,后续命令却找不到预期的 OHOS 平台。定位这种问题,比反复重装依赖更重要的是确认实际执行文件在哪里。
对于 DevEco Studio,重点记录开发套件版本、已装的 HarmonyOS SDK、Hvigor 和 Node.js 配套关系。官方 26.0.0 Release 文档给出了相应版本清单,项目应以本机 About 和 Toolchain 输出为准。尤其不能把 IDE 升级到新版本,却让 CI 长期使用另一套旧工具链,最后出现“本地能编、流水线不能编”。
uni-app x 则要记录 HBuilderX 的完整版本以及本机 DevEco Studio 位置。DCloud 文档说明,鸿蒙端的 UTS 构建依赖本地 DevEco Studio 工具链,不能套用 Android/iOS 的所有发行经验。插件如果用了额外的 ArkTS 接口,还需要确认它所依赖的系统 API、权限和可运行设备。
除了记录版本信息,还需要在目标设备上检查应用的实际界面与运行表现。

我会将这些信息落成一个 environment.md,而不是贴在聊天记录里:
项目:随行清单
目标系统:HarmonyOS 7 / API 26.0.0
DevEco Studio:见本机构建记录
Flutter OH 标签:见版本锁定文件
Flutter Engine:与适配 SDK 配套
HBuilderX:见发行版记录
构建机操作系统:见 CI Agent 信息
签名方式:Debug / Release 分开记录
设备:系统版本、API 版本、设备型号分别登记
这样的记录看起来不复杂,却能让两个月后接手项目的人知道应该从哪里复现问题。
四、同一套业务,不必强行写成同一种工程
“随行清单”的业务模型很小:清单分类、条目标题、完成状态、最后更新时间。Flutter 和 uni-app x 只需要共享业务语义和验收样例,不必为了表面上的一致,把两个框架的目录结构改得一模一样。
Flutter 路线以 Dart 作为业务和 UI 核心,配合 OHOS Engine 与宿主工程。我的目录分层大致如下:
travel_checklist_flutter/
├─ lib/
│ ├─ app.dart
│ ├─ model/check_item.dart
│ ├─ pages/checklist_page.dart
│ └─ services/checklist_repository.dart
├─ ohos/
│ └─ entry/ # OHOS 宿主工程相关内容
├─ pubspec.yaml
└─ compatibility/ # 本系列共用的验证记录
Dart 数据结构不需要知道自己运行在哪个平台:
class CheckItem {
const CheckItem({
required this.id,
required this.title,
required this.done,
});
final String id;
final String title;
final bool done;
CheckItem copyWith({bool? done}) => CheckItem(
id: id,
title: title,
done: done ?? this.done,
);
}
页面里只做任务切换、列表渲染和状态反馈,不在这一步加入大量设备能力。平台判断也要谨慎:在 Flutter for OpenHarmony 的适配 SDK 中,可以参考社区样例使用 defaultTargetPlatform == TargetPlatform.ohos 识别目标平台;但这不是普通上游 Flutter SDK 都能直接使用的枚举值。
uni-app x 路线则采用 .uvue 页面、UTS 数据和组件,结构可能是:
travel_checklist_unix/
├─ pages/
│ └─ checklist/checklist.uvue
├─ components/
├─ uni_modules/
├─ manifest.json
├─ pages.json
└─ compatibility/
UTS 页面里,最初只做同样的清单切换:
<template>
<view class="page">
<text class="title">随行清单</text>
<view v-for="item in items" :key="item.id" class="row">
<text>{{ item.title }}</text>
<text>{{ item.done ? '已完成' : '未完成' }}</text>
</view>
</view>
</template>
<script setup lang="uts">
type Item = { id: string; title: string; done: boolean }
const items = ref<Item[]>([
{ id: 'a1', title: '确认车票', done: true },
{ id: 'a2', title: '整理资料', done: false }
])
</script>
这段只是让业务语义对齐。真正涉及 UTS 插件和权限的细节,会放在第三篇深入处理。

五、版本矩阵不该是一张“红绿灯截图”
如果只写“版本 A 支持,版本 B 不支持”,矩阵很快就会过期。我的做法是在表格里增加三个更有价值的字段:证据、失败原因、重测日期。
可以把验证记录存成 CSV,方便 CI 和人工回归一起维护:
id,framework,framework_build,api_version,scenario,status,evidence
F001,Flutter-OH,lockfile,26.0.0,startup,PENDING,
F002,Flutter-OH,lockfile,26.0.0,plugin-channel,PENDING,
U001,uni-app-x,lockfile,26.0.0,startup,PENDING,
U002,uni-app-x,lockfile,26.0.0,uts-capability,PENDING,
状态只用几个明确值:PENDING、PASS、FAIL、BLOCKED。其中 BLOCKED 表示无法开始验证,例如证书、工具链或设备未就绪;它不能被写成框架“不支持”。
再补一个很轻量的检查脚本,防止有人在版本矩阵里留下空白结论却把总表标成通过:
import csv
from pathlib import Path
path = Path('compatibility/matrix.csv')
rows = list(csv.DictReader(path.open(encoding='utf-8-sig')))
for row in rows:
status = row['status'].strip().upper()
if status == 'PASS' and not row['evidence'].strip():
raise SystemExit(f"缺少验证证据: {row['id']}")
print('矩阵记录完整性检查通过')
脚本的定位非常明确:它只验证记录是否完整,不会替开发者判断 Flutter Engine 与 API 26 是否真的兼容。

插件版本是矩阵里最容易漏掉的第二张表
兼容表里只有框架和系统版本远远不够。跨端项目真正容易卡住的地方,通常是插件。比如“随行清单”第一版只用到了基础列表,Flutter 的页面很好移植;第二版增加文件选择和系统分享以后,可能发现同名插件在 Android 和 iOS 都能工作,但 OHOS 侧需要安装一个不同维护分支,或者根本没有相应的平台实现。
我会为每个三方依赖补一行记录:插件用途、Dart/UTS 版本、是否提供 OHOS 平台目录、关联仓库、最后维护日期、权限需求和 Release 验证状态。这张表不用把全部传递依赖逐一写成人话,但直接使用的原生插件必须列全。
最实际的检查方式不是搜索一篇“某插件支持鸿蒙”的文章就算结束,而是打开对应仓库的发布分支,核对 ohos 平台实现、声明的最低框架版本、最近的兼容修复记录和示例工程。Flutter 社区的 CPF-Flutter 已经维护了已适配插件清单和样例仓库,它非常有参考价值,但项目仍需要对具体插件版本做自己的结论。uni-app x 的 UTS 插件同理,要看当前 HBuilderX 版本和平台兼容表,而不是只看插件名称。
如果插件没有 OHOS 实现,矩阵中我会直接标成 BLOCKED 并给出备选方案,例如使用 ArkTS 原生能力重新封装一个最小接口;这比把“暂时不能用”留到发布阶段才说清楚成本更低。
六、升级 API 26 时,最有用的是“变更影响清单”
华为官方在 API 26 升级指南里提供了 API 变更助手,可在 DevEco Studio 的 Tools → API Change Assistant 中选择版本范围,扫描当前工程可能受到的 API 变更影响,并导出结果。对跨端团队来说,它的价值不是自动帮 Flutter 或 UTS 改好代码,而是把宿主工程中已经使用的 ArkTS API 变化先找出来。
我会将扫描结果拆成三类:
- 宿主工程变化:
module.json5、ArkTS、签名、权限、生命周期相关变化; - 框架接入变化:OHOS Engine、平台插件、UTS 原生调用可能受到的影响;
- 业务行为变化:页面返回、深色模式、文件访问、数据恢复等需要人工验证的体验。
这种做法能避免一个常见误区:工程“无编译错误”并不表示运行行为没变。比如文件选择器返回的 URI 授权时效,可能不会在编译阶段报错,却会影响应用从后台回到前台后的处理流程。

七、跑通第一屏以后,至少要过这些场景
第一篇的 Demo 不做很重的业务,但也不能只拍一张首页就结束。我给 Flutter 和 uni-app x 准备同一套基本场景:
| 场景 | 通过条件 | 留存证据 |
|---|---|---|
| 首次启动 | 页面能进入,清单分类正常显示 | 设备与首页截图 |
| 条目切换 | 完成状态正确更新,不错乱 | 操作记录 |
| 页面往返 | 进入详情再返回,列表位置符合预期 | 录屏和日志 |
| 前后台 | 应用恢复后不丢当前页面状态 | 前后台操作记录 |
| 字体尺寸 | 系统字体放大后重要文字仍可读 | 不同字号截图 |
| 深浅色 | 背景和文字对比度可接受 | 两种主题截图 |
| 插件调用 | 原生能力有返回或明确错误 | Channel / UTS 日志 |
| Release 构建 | 能生成目标包,签名配置一致 | 构建日志与产物信息 |
这里有一个关键约定:两套框架可以采用不同技术实现,用户能看见的业务结果要一致。比如 Flutter 采用一个 Widget 列表,uni-app x 采用 .uvue 组件,只要完成状态、返回行为与恢复规则一致,就不应该为了技术结构不同而判失败。

还有三项单独检查:一是插件矩阵,不能把 Android/iOS 上装过的包直接视为有 HarmonyOS 实现;二是签名与权限,Debug 通过并不等于正式包已经具备相同能力;三是设备 API,不能只看系统名称,必须读取设备的实际 API 版本。框架支持范围、应用 SDK 配置和设备能力三者都要吻合。
构建产物也要能回答“从哪台机器出来的”
一个工程通过开发环境检查以后,还需要留下构建产物来源。如果没有这一步,后面出现“相同提交构建结果不同”,你很难判断是代码问题还是工具链问题。
我建议每次候选发布至少留下面几项:Git commit、框架适配标签、锁文件哈希、DevEco/Hvigor 版本、签名方案、构建日期以及最终包的 SHA-256。这个清单不用做成复杂平台,用一份文本文件配合 CI 归档就能开始。
例如,Linux/macOS 构建机可以在产物生成后执行:
# 在已经找到对应的 .app 或 .hap 文件后执行
shasum -a 256 path/to/release.app > artifact.sha256
# Linux 也可以使用 sha256sum
还要记录这是 Debug 包还是 Release 包。二者可以使用不同证书、不同构建配置、不同混淆和资源压缩规则,不能只因为 Debug 包在开发设备上打开就宣称整条正式发布链路成立。
当 Flutter 和 uni-app x 两份工程进入 CI 时,我会让它们使用相同的验收用例,但分开执行构建。不要为图方便把两套工具都塞进一份不可复用的临时脚本里。Flutter SDK 和 HBuilderX 分别有自己的版本和构建前提;一条流水线能把两个入口分清楚,比表面上只有一个“Build All”按钮更重要。
跨端的“一致”还要覆盖 UI 与交互,而不只是数据
举个很小的例子:清单页有一个悬浮的新建按钮。Flutter 默认的安全区计算、文字缩放与点击反馈,与 .uvue 页面中相应布局可能并不完全相同。两边逻辑都能勾选清单,不代表在不同屏幕尺寸上使用感觉一致。
所以我还会准备一份最小视觉与行为基线:首屏重要信息是否可见;系统字体放大后按钮会不会挤出屏幕;深色模式下分割线是否仍清晰;键盘弹起时输入框有没有被遮住;返回键与手势返回是否恢复相同页面。截图只用于辅助比对,真正的通过条件还是交互结果。
最重要的是,不要把 Flutter 组件和 uni-app x 组件的像素坐标硬凑成相同值。平台默认间距、响应式布局和文字度量不同,先建立统一的设计意图,再让各自框架按自身机制落地,比“每个像素都一样”更可维护。
一份真正有用的版本锁定文件,应当包括什么
当我把候选版本交给团队时,会让大家在同一个文件里登记,而不是每个开发各自存一张截图。对于 Flutter,至少写上仓库 URL、分支或 tag、Git commit、Engine 来源、Dart 版本、使用到的 OHOS 插件清单;对于 uni-app x,则记录 HBuilderX 完整版本、运行模式、UTS 插件和导出工程对应的工具版本。除了这些,还要记录测试设备的 ROM API,以及 CI 镜像或本机构建环境。
为什么要细到 commit?因为仅仅写一个大版本号,未必能区分社区对同一个基线发布的多次修订。如果插件和 Engine 的编译产物来自不同修订,编译问题或运行时差异就会变得难追踪。
对清单类应用而言,最先需要验证的三个业务场景是:清单勾选是否稳定、页面往返后状态是否保留、通过原生插件操作文件时错误是否可控。只有这三个场景明确通过,版本矩阵里的“可以进入功能开发”才有实际意义。否则项目可能已经安排好了页面开发,却仍旧不知道最关键的系统接入能不能跑通。
最后,兼容矩阵一定要有负责人。框架更新由谁评估、插件冲突谁处理、证据谁复核、发布前谁最后签字,都要在记录里写清楚。没有负责人,版本矩阵很容易变成一次评审会上很好看、评审完没人维护的表格。
再补一个团队里很实用的习惯:每次升级只动一条变量。比如先固定 HarmonyOS SDK 和 DevEco Studio,只升级 Flutter OH 分支;如果验证通过,再单独升级插件。不要同一天把框架、Engine、插件、Node.js 和打包配置全部替换,否则出了问题根本无法判断是哪一步引起的。哪怕一次只验证两个小场景,也比同时改动七八项后只留下一个“构建失败”的结论更有用。
八、第一篇的交付不是“选 Flutter 还是 uni-app x”
我没有在这一篇给 Flutter 和 uni-app x 排名,因为我们还没进入足够有说服力的性能、插件适配和长期维护阶段。现在能得出的结论只有几个。
第一,HarmonyOS 7 / API 26 有清楚的官方 SDK 基线,项目不能只写“适配鸿蒙”而不锁定具体 SDK。第二,Flutter for OpenHarmony 要锁定带 OHOS 适配的框架和 Engine;单看上游 Flutter 版本会漏掉关键条件。第三,uni-app x 的鸿蒙支持已经有官方路线,但 HBuilderX 起始版本并不等于所有业务 API 在 API 26 上已经完成验证。第四,所有绿色结论都必须能对应设备、构建记录和测试证据。
这一阶段真正需要交接的东西,是版本锁定表、环境记录、API 变更清单、最小业务工程和待验证列表。这些资料没必要写得很复杂,但必须能让新同事跟着走一遍。

下一篇会沿着 Flutter 路线向下走一层:当“随行清单”需要从系统文件选择器导入一份清单时,Dart 页面如何通过 Platform Channel 调用 HarmonyOS 的文件访问能力;用户离开应用、返回应用、取消选择时,又该怎样维护一条清楚的生命周期链路。
参考资料与版本说明
- 华为开发者:应用升级适配指导(26.0.0):https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/upgrade-adaptation
- 华为开发者:HarmonyOS 开发套件版本总览:https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/overview-allversion/
- 华为开发者:Flutter for OpenHarmony 方案:https://developer.huawei.com/consumer/cn/doc/guidebook/solution-0000002784651007/
- CPF-Flutter 仓库:https://gitcode.com/CPF-Flutter/flutter_flutter
- DCloud:uni-app x 鸿蒙开发指南:https://doc.dcloud.net.cn/uni-app-x/app-harmony/
- DCloud:兼容性表格导读:https://doc.dcloud.net.cn/uni-app-x/tutorial/compatibility.html
更多推荐




所有评论(0)