跨端项目最让人头疼的时刻,不是某个按钮还差 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 SDKAPI 26.x 的具体版本接口与工具链依赖
DevEco Studio / Command Line Tools安装包版本与来源Hvigor、ohpm、hdc 环境
JDKjava -version编译链兼容性
Node.jsnode --version工具任务和包管理
Hvigorhvigorw -v构建任务行为
ohpmohpm -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/
Logo

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

更多推荐