【跨端】HarmonyOS 适配与交付指南 05|多框架构建、签名与持续回归【鸿蒙心迹】
跨端项目最让人头疼的时刻,不是某个按钮还差 8 个像素,而是发布前一天有人问:“这份安装包到底用哪个分支、哪个工具版本构建的?”
“随行清单”已经有 Flutter 和 uni-app x 两条路线,后续还需要保留 React Native 的适配评估。三条路线的代码库、依赖和工程形态不一样,但发布负责人最想收到的其实是同一组材料:能追溯的构建包、明确的签名与版本信息、检查结果、设备回归记录。
这篇是五连载的最后一篇。我不想把 CI 写成一个五颜六色的流程图,更不想在终端看到一个绿色 BUILD SUCCESSFUL 就宣布“多平台适配完成”。我们真正要解决的是:不同框架生成的鸿蒙工程,怎样在同一套发布规则下交接、构建、归档和验收。
本篇以 HarmonyOS 7 / API 26 为目标,采用“HBuilderX 或框架工具完成各自源工程准备,Hvigor 对生成的鸿蒙工程执行可追溯构建,CI 负责固定环境和门禁”的拆分。这样既尊重不同框架的真实构建方式,也不需要编造一个所有框架都能调用的万能命令。

一、先画清楚三类构建对象,别把源工程和发布产物混在一起
Flutter 路线通常有 Dart 业务工程、Flutter for OpenHarmony SDK/Engine,以及生成或维护的 OHOS 宿主工程;uni-app x 路线由 HBuilderX 管理 .uvue、UTS 和 manifest.json,编译产物中包含鸿蒙原生工程;React Native 路线则还取决于当前 HarmonyOS 适配分支、原生模块与包管理配置。
这三者可以共用一份业务数据协议,却不适合强行共用同一条框架编译命令。真正能统一的,是更靠后的发布行为:验证工程来源、执行 Hvigor、检查版本和签名、做回归并归档。
Flutter source ----- Flutter OHOS 工具链 ----\
\
uni-app x source --- HBuilderX 生成工程 ---> HarmonyOS 原生工程
/ ↓
React Native source - 对应鸿蒙适配构建 ------/ Hvigor
↓
HAP / APP + manifest
↓
签名检查 + 设备回归
↓
发布归档
可以在 DevEco Studio 中核对生成工程和构建配置,记录待确认的工具链信息。

在工程仓库里,我额外放了一个 release-manifest.json 作为交接记录,专门保存源提交、框架适配版本、生成工程位置、构建工具版本、目标 API、输出文件和校验摘要。文件里不存私钥,也不写口令。
{
"project": "travel-checklist",
"targetApi": "26.0.0",
"framework": "uni-app-x",
"sourceRevision": "<git-commit>",
"frameworkTool": "<HBuilderX-version>",
"nativeProject": "dist/harmony-project",
"buildMode": "release",
"artifact": "outputs/travel-checklist.app",
"sha256": "<calculated-after-build>"
}
真正落地时,nativeProject 位置要由当前 HBuilderX 导出的工程确定,而不能把这里的交接字段当成 HBuilderX 固定目录规范。因为不同版本、不同工程模板可能对生成目录做出调整。我们只要求每次打包都能追到“哪个源版本生成哪个原生工程”。
二、固定工具链版本,比写一千行 YAML 更重要
CI 最常见的隐患是:脚本没有变,工具环境却悄悄变了。一台机器升级了 Node.js,另一台还留着旧的 SDK,构建结果就可能不再一致。
我给构建机做了一张版本锁定表:
| 工具 | 记录方式 | 为什么要锁 |
|---|---|---|
| HarmonyOS SDK | API 26.x 的具体版本 | 接口与工具链依赖 |
| DevEco Studio / Command Line Tools | 安装包版本与来源 | Hvigor、ohpm、hdc 环境 |
| JDK | java -version | 编译链兼容性 |
| Node.js | node --version | 工具任务和包管理 |
| Hvigor | hvigorw -v | 构建任务行为 |
| ohpm | ohpm -v | 三方依赖解析 |
| Flutter OHOS | 仓库提交或 Release 标签 | Engine 与插件组合 |
| HBuilderX | 实际安装版本 | UTS 编译和生成工程 |
华为官方命令行构建指南在 Command Line Tools 26.0.0 及以上版本推荐 JDK 21。这里我不会写死一个没有校验过的“统一环境包”,而是根据目标工具版本创建构建镜像,并把版本输出保存到每次任务日志。尤其是 Windows 长路径和 uni-app x 编译生成目录的问题,最好在工程命名阶段先控制路径深度。
构建环境核查之后,还需要在目标设备上检查应用页面和关键操作。

脚本里首先执行的不是打包,而是环境检查:
#!/usr/bin/env bash
set -euo pipefail
echo "=== Build environment ==="
java -version
node --version
ohpm -v
hvigorw -v
test -d "${NATIVE_PROJECT}" || {
echo "Native project missing: ${NATIVE_PROJECT}" >&2
exit 21
}
test -f "${NATIVE_PROJECT}/build-profile.json5" || exit 22
其中 NATIVE_PROJECT 是当前框架产出或签入的实际鸿蒙工程目录。CI 不负责凭空生成它;如果上游 HBuilderX 或 Flutter 步骤没有执行完成,就让这条检查明确失败,而不是拿昨天留下的目录继续打包。
三、Hvigor 要做的不是“一个 build 命令”,而是可审查的 Release 构建
华为官方文档给出的构建入口是 hvigorw,可以执行 clean、assembleHap、assembleApp 等任务,并明确指定 product 与 buildMode。面向提审的 APP 与用于设备安装的 HAP 并不是一个概念:这两种产物的用途、签名与校验流程必须单独记录。
#!/usr/bin/env bash
set -euo pipefail
cd "${NATIVE_PROJECT}"
ohpm install
hvigorw clean --no-daemon
hvigorw assembleApp --mode project \
-p product=default \
-p buildMode=release \
--no-daemon
这个命令用的是官方公开的 Hvigor 任务和参数;前提是当前工程已经配置了对应的 product、签名/发布方案和所需依赖。若只是跑调试环境,则另外使用 assembleHap 和 debug 模式,而不是把 debug 包改个文件名直接提交。

“成功生成”之后还要核对输出目录。官方说明 APP 产物位于工程的 build/outputs/{productName}/,HAP 则位于模块对应的 build/{productName}/outputs/{targetName}/。CI 必须按构建目标查找,而不是全仓库搜索第一个 .app 或 .hap;否则非常容易把上一次构建遗留的产物当成新包。
我会在执行前清空该任务独立的输出目录,完成后只收集被配置允许的目标路径,并将文件名、大小、SHA-256、构建时间、源提交写入归档清单。
四、签名是单独的门禁,不应该藏在构建成功后面
跨框架工程最终都要遵守 HarmonyOS 的签名与发布规范。这里我给自己定了两条规则:构建机不能输出私钥内容,签名状态不能只靠肉眼看文件名。
签名信息由 CI 的受控密钥管理或官方发布平台能力提供。需要发布签名时,使用已核对的证书和配置;如果采用开发者中心支持的云管理证书/重签名流程,则在交付单中说明采用哪一套方案,而不是把自有证书与云管理流程混成一句“已签名”。
对每一份交付产物,我记录如下字段:
bundleName / appIdentifier
versionName / versionCode
product / buildMode
certificateStrategy
artifactPath / artifactType
sha256
sourceRevision
reviewedBy
如果版本号和包名不一致,即使 CI 绿了,也不允许把它送进下一步。签名失败时停止任务,不能退化成上传未签名安装包继续尝试。测试包与发布包也必须分目录归档,避免出现“同名同版本、证书不同”的情况。
五、HBuilderX 的责任在上游,不强行把它写成 Hvigor 插件
uni-app x 的鸿蒙构建有它自己的入口。DCloud 官方说明,鸿蒙开发需要本地安装 DevEco Studio 支持的工具链,HBuilderX 提供运行、日志、发行与调试证书等能力,生成的原生工程可在其构建输出中找到。DCloud 还强调,权限并不会因为使用了一个 API 就自动全部写进最终包。
所以在这套流水线中,HBuilderX 负责把 pages/、UTS、manifest 等源文件编译为鸿蒙工程;Hvigor 负责在受控环境下完成原生工程构建。如果当前 HBuilderX 版本提供受支持的批处理入口,团队可以在上游自动化调用;如果没有,就明确把生成原生工程作为需要确认的输入工序,而不是编造一个永远有效的 hbuilderx build harmony 命令。

这一分工还解决了一个常见争议:代码审核到底看 .uvue 还是看生成的 ArkTS?业务逻辑与 UTS 改动应主要审核源代码;生成工程则要检查 API、权限、签名和构建参数,必要时定位编译问题,但不把对生成文件的临时手改当作可长期维护的修复。
六、CI 必须有门禁,而不是只有一串任务名称
我把流水线的检查分为五关:环境完整、源版本固定、构建完成、产物一致、设备回归。任何一关没有证据,就记录“待检查”,而不是自动填绿色勾选。
name: harmony-cross-build
stages:
- verify_inputs
- build
- inspect
- test
- archive
verify_inputs:
script:
- bash tools/check-env.sh
- python3 tools/check-release-manifest.py
build_native:
script:
- bash tools/build-harmony.sh
inspect_artifacts:
script:
- python3 tools/hash-artifact.py
- python3 tools/check-artifact-metadata.py
regression:
script:
- bash tools/run-device-regression.sh
archive:
script:
- bash tools/archive-release.sh
这是一份团队可读的流水线结构清单,不是某家 CI 平台可以直接执行的完整配置;落地时需按 GitLab CI、Jenkins、GitHub Actions 或企业平台的实际任务语法适配,并补齐 Runner、凭证、依赖缓存和产物传递。这样写比把一个外部平台的私有 DSL 强塞给所有读者更诚实,也更便于迁移。

为了保证报告可追溯,测试结果至少包含 deviceApi、设备形态、框架分支、artifactSha256、场景 ID、时间戳和失败截图路径。异常日志与个人数据要按发布流程做脱敏,设备回归证据不能直接包含用户的真实清单内容。
七、兼容性回归不能由“编译成功”代替
最后一关才是设备。三套框架都能生成包,不代表它们在真实设备上的体验已经一致。针对“随行清单”,我只把团队确实维护的关键场景列为必验项:清单首次打开、勾选状态保存、文件导入、拒绝权限后恢复、前后台切换、深浅色和屏幕尺寸变化。需要时再补平板、折叠屏、大字体、系统导航模式等。
| 检查组 | 必须记录 | 失败时归属 |
|---|---|---|
| 启动与导航 | 首屏、Tab、返回行为 | 框架或业务层 |
| 文件与权限 | 选择、取消、授权、再次访问 | 原生桥接/配置 |
| 业务状态 | 勾选、草稿、重进恢复 | 业务存储层 |
| 多尺寸 | 安全区域、横竖屏、折叠态 | UI 适配层 |
| 性能与稳定性 | 启动耗时、异常日志、内存变化 | 性能与资源层 |
| 发布包 | 签名、版本、包名、资源、构建指纹 | 构建与发布 |


打包完成后的回归任务需要引用同一份 SHA-256 产物。否则工程师在本地重新构建一份“差不多相同的包”进行测试,发布平台最后上传另一份包,回归报告就失去依据。问题修复后也不要只补一张截图,而应该让相同设备与相同操作步骤再跑一次,明确区分修复前后的源码提交和包体指纹。
八、给下一次发版留下真正能接手的东西
第五篇做完,我最想得到的不是一个绿色的“完成”动画,而是下一次换人发布时,接手者不需要找昨天的聊天记录。仓库里应该留有工具链锁定表、生成工程交接单、构建脚本、签名方式说明、制品校验文件、测试用例与问题闭环记录。所有文件跟着相应版本归档,遇到失败可以按源提交和构建指纹定位。
这也是五连载最终的落点:01 先定 API 与版本组合;02 把 Flutter 文件访问与生命周期接好;03 处理 uni-app x 的鸿蒙权限和页面行为;04 用开发助手帮助形成更有效的修复流程;05 再把这些改动放进受控的发布链路。
跨端的真正“统一”,不是让三个框架使用同一份构建命令,而是让它们接受同一套清楚、可审查、可复验的交付标准。 当每次构建都能回答“从哪里来、用了什么版本、出了什么包、在哪些设备上检查过”,团队才算建立了可持续的 HarmonyOS 7 跨端工程体系。
九、先补一个真正能运行的产物校验脚本
仅靠构建工具返回零退出码,无法证明 CI 拿到的是正确的文件。我给工具目录增加了一个小脚本:输入目标文件,输出大小与 SHA-256,并根据文件名判断是否属于允许的产物类型。它不负责判断签名是否有效;签名有效性应通过官方工具和发布平台单独核对。
from pathlib import Path
import hashlib, json, sys
path = Path(sys.argv[1]).resolve()
if not path.is_file() or path.suffix not in {'.app', '.hap'}:
raise SystemExit('invalid artifact')
h = hashlib.sha256()
with path.open('rb') as f:
for chunk in iter(lambda: f.read(1024 * 1024), b''):
h.update(chunk)
print(json.dumps({
'file': path.name,
'sizeBytes': path.stat().st_size,
'sha256': h.hexdigest()
}, ensure_ascii=False, indent=2))
脚本只接受一个明确路径,不会在整个仓库里搜索“最新的文件”。在流水线配置里,这个路径应来自当前构建任务成功写出的产物清单,并与目标 product 绑定。下一步才能让测试 Runner 使用同一摘要下载产物。没有这个步骤,构建与测试很容易各自拿一份不同的包。
十、并发发版最怕的是两条流水线抢同一套签名环境
如果两个分支同时触发 CI,一个负责日常测试,一个负责发布 Release,签名文件和输出目录若共用同一个位置,很容易出现不可解释的冲突。我的处理方式是把任务运行目录按提交与流水线 ID 隔离:
work/${pipelineId}/${sourceRevision}/
source/
native-project/
build-output/
reports/
对需要访问发布凭证的阶段,限制只有受信任分支和受授权 Runner 可以执行;正常开发分支只构建调试包,不接触发布证书。日志也不输出凭证变量的值。这样的分工比事后检查“为什么 CI 找不到签名”更加可靠。
此外,上游 HBuilderX 工程如果还没有生成,后续 Hvigor 任务必须失败,而不是使用缓存里留下的旧目录。缓存适合保存可验证的依赖包,却不能不经检查复用上一轮带有构建配置的原生工程。
十一、回归报告要能还原当时运行的环境
一份合格的设备报告,至少应回答六个问题:谁执行、什么设备、哪个系统 API、哪份产物、测试了什么、最后是什么结果。只保存“打卡成功”的截图,既不能证明权限路径,也不能帮助下一位工程师复现失败。
{
"caseId": "CHECKLIST-PERMISSION-RETRY",
"deviceModel": "<填入设备型号>",
"systemApi": "<读取设备版本>",
"framework": "<Flutter或uni-app x等>",
"artifactSha256": "<产物摘要>",
"steps": ["拒绝授权", "进入设置", "返回应用", "再次尝试"],
"result": "pending",
"evidence": []
}
这份结构也方便后续汇总:某个 API 版本上,某一类文件访问问题出现频率更高;或者某个 framework/Engine 组合始终无法正确返回。这比口头汇报“这版好像更稳了”有用得多。
十二、发布前还要有一份不能靠工具自动回答的清单
有些发布问题无法由 assembleApp 自动保证:业务隐私说明与实际调用权限是否一致,用户拒绝访问后是否有合理降级,客服和产品是否准备好审核补充材料,版本号、更新说明和功能截图是否已经核对。它们同样影响能否顺利交付。
所以最终门禁有两个维度:机器可核的工程门禁和需要负责人确认的发布门禁。前者包括构建、包结构、摘要、签名信息、设备用例;后者包括权限理由、隐私告知、商店材料、问题关闭记录。任何一项都不应该被“构建成功”这个结果覆盖。
另外,正式发布时,不要把文章中的配置片段直接复制到生产 CI。证书策略、项目 product、Runner 的操作系统与官方命令行工具路径都要按企业自己的仓库重新核对;尤其是 HarmonyOS 7 / API 26 的具体 SDK 修订号,必须写入实际版本锁定文件,而不是仅凭文章标题推断。
十三、包体相同不意味着流程相同,流程相同也不意味着包体相同
构建追踪时常见一个误区:只要版本号一样,就认为两个 .app 是同一版本的产物。实际上同名版本可能来自不同源提交,也可能采用不同签名方式、依赖版本或构建选项。因此 CI 的唯一引用至少需要“源码提交 + 构建配置 + 输出 SHA-256”三个维度,而不是只记录 1.0.0。
相反,即便两次 CI 使用相同命令,也可能由于依赖仓库更新、工具链没有固定、时间戳或打包选项变化而得到不同摘要。出现这种情况时,不要直接宣称“构建不稳定”,先比较锁文件、工具版本和生成工程差异。对需要严格可复现的项目,还应逐步控制环境镜像、依赖下载源和构建输入文件,而不是把构建结果不一致全部归到 Hvigor。
十四、发布失败时,回滚应该回到“版本组合”而不是回到一行代码
假如第 05 篇处理的是一次正式上线前的回归,用户在某台折叠屏上发现清单按钮被遮挡。开发很容易把对应 CSS 调回去,再触发一轮构建;但这样会漏掉一层风险:本次版本里可能还有框架分支、系统 SDK 和原生插件的配套变化。
我会先确认失败属于业务 UI、原生桥接还是构建配置。如果只是页面组件问题,回退最小业务提交;如果根因是插件与 Engine 版本不匹配,就回退整组已锁定的框架依赖,并重新输出一份产物摘要。绝不允许用旧安装包的测试截图去证明新构建包已经恢复。
这种处理方式很适合多框架团队,因为 Flutter、uni-app x 和 React Native 并不是同时升级的。它们可以各自回滚,却应在发布台账中保留清楚的“哪条路线目前可发布、哪条路线仍待回归”的状态。业务可以决定是否延后某个平台,但不能把未通过检查的结果用其他平台的绿色状态覆盖。
十五、把“提交发布”从个人操作变成团队交接
最后一步不是再加一个 Build 按钮,而是把岗位责任说清楚:开发负责工程源与工具链,测试负责设备和业务路径,安全或发布负责人审核签名与权限,产品核对版本描述和截图。每个角色只确认自己能核查的内容,并且都引用同一份产物摘要。
如果用户后续反馈某项功能异常,我们就能从包名和 SHA-256 找到对应提交、依赖锁文件、构建日志、设备报告和发布审批记录。换句话说,这次真正补齐的是一条从源码一直追到应用安装包的证据链,其他同事接手时不用再从头猜“当时是谁打的包”。
资料与版本核对
- 华为 Hvigor 命令行流水线:https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/ide-command-line-building-app/
- DCloud 鸿蒙开发指南:https://doc.dcloud.net.cn/uni-app-x/app-harmony/
- HarmonyOS 开发助手版本说明:https://developer.huawei.com/consumer/cn/doc/start/hosdevassistant-version-0000002618910899/
更多推荐


所有评论(0)