一套应用在 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 路线要锁定什么
系统与 SDKHarmonyOS API 26.0.0、设备实际 API 版本HarmonyOS API 26.0.0、设备实际 API 版本
框架CPF-Flutter 适配分支及提交/Release 标签HBuilderX 版本及内置 uni-app x 运行时
构建DevEco Studio、Hvigor、ohpm、Node.js、DartHBuilderX、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 SDK26.0.0 Release官方推荐构建机和设备 API 截图
DevEco Studio26.0.0 Release 配套版官方推荐About / SDK 信息
Flutter OHCPF-Flutter 3.41.9 系列稳定产物社区适配版本可用锁定具体标签、Engine 与插件
uni-app xHBuilderX 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
Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐