Hvigor + HarmonyOS 应用发布:版本配置防漂移(连载01/06)【共创稿事节】
应用打包能完成,不代表发布配置一定正确。有的团队在提交前才发现版本号没有递增,有的团队测试包和正式包误用了同一套构建模式,也有人在应用配置里改了版本,随后又被构建脚本覆写。最难排查的往往不是一条报错,而是“每个人都改过一点配置,最终产物到底采用哪一份”这个问题。
要让 HarmonyOS 的上架过程可追踪,第一件事不是堆自动化命令,而是确认应用身份、版本信息、构建模式和签名材料各自属于哪一层。本文把发布流程收紧为一个工程化的最小闭环:配置责任划分、版本号规则、构建前静态检查、构建模式核对,以及失败时直接停止的门禁逻辑。目标是把原来依靠人工记忆的事项变成能解释、能核对的工程约束。

四份配置,别让职责混在一起
基于 Stage 模型的 HarmonyOS 工程通常存在一个 AppScope/app.json5 和一个或多个模块级 module.json5。前者承担应用级身份与版本等配置,后者描述对应模块、Ability 和相关资源;build-profile.json5 规定构建目标、产品及模式相关选项,而 hvigorfile.ts 则参与定义和扩展构建流程。不能因为它们都是 JSON5 或 TypeScript 文件,就把它们当成随意重复填写相同字段的地方。
例如 bundleName 应与应用市场配置中的应用身份一致;versionCode 是用于区分迭代的数值标识,versionName 是面向版本展示的字符串。release 与 debug 表达的是构建行为,签名配置关联证书、profile 等材料,不能拿“是不是正式包”去代替版本号递增验证。对正式发布而言,更稳妥的顺序是先定版本,再审查构建配置,最后选择适用的发布签名和交付方式。

最容易造成漂移的是双重配置源:一方面在 app.json5 填写一个静态 versionCode,另一方面又在 hvigorfile.ts 的 hook 中动态赋值。构建系统有能力改写这些配置,但“能改”不等于“每个项目都应该改”。华为官方文档提供了通过插件上下文的 getAppJsonOpt() 与 setAppJsonOpt() 更新应用配置的方案。对于最初的交付流水线,我们反而选择更保守的策略:版本号只有一个受代码审查的静态来源,在验证通过前不做构建时覆盖。这样每个候选包的版本含义可以与代码提交准确对应。
用稳定版本号替代时间戳猜测
假设维护中的项目准备发布 1.2.0,并采用 1002000 作为这次候选版本的示例编码。编码策略应由团队统一规定,后续版本严格递增;这里的数字只是示例,不是 HarmonyOS 强制的版本映射算法。
// AppScope/app.json5 片段,其他字段保留工程已有配置
{
"app": {
"bundleName": "com.example.fieldops",
"vendor": "example",
"versionCode": 1002000,
"versionName": "1.2.0"
}
}
实际工程里该文件还可能含有图标、标签、API 版本等配置,不能为了复制片段把已有字段整份删掉。bundleName 一旦进入正式分发体系,就应按应用身份管理流程变更,绝不能把调试时临时包名误写成新版本的正式标识。版本编码也不能使用“当前时刻随机生成”的方法:同一源码提交在不同日期构建出不同版本号,给问题复现、灰度回滚和发布追溯都带来麻烦。
versionName 并不承担大小比较的任务。字符串 1.10.0 和 1.9.0 若直接按字典序比较,结果可能违背人的版本认知;真正需要判断能否升级时,应采用团队制定的数值编码策略和正式市场规则。通常要求新版本的 versionCode 大于已发布版本的编码,尤其要避免多个分支对同一正式版本号重复发包。
构建前门禁:先检查,再碰签名
静态检查有个非常实际的好处:它不需要先触碰正式发布证书,也不需要等待整个工程完成编译。下面使用 Node.js 与 json5 包读取工程配置,检查应用身份、语义化显示版本以及数值版本是否高于已发布基线。这个脚本是独立的发布前辅助脚本,不是 HarmonyOS SDK 的系统接口;运行前在工程外层辅助工具环境安装 json5 依赖。
npm install --save-dev json5
node tools/check-release.mjs 1001999
这里的 1001999 是示例上一已发布版本编码。实际流水线应从受控的发布记录读取它,不要把“上一版是多少”散落在成员口头沟通和本机文件中。
// tools/check-release.mjs:基于 Node.js 的构建前检查
import { readFileSync } from 'node:fs';
import JSON5 from 'json5';
const previous = Number(process.argv[2]);
if (!Number.isSafeInteger(previous) || previous < 0) {
throw new Error('必须提供合法的上一已发布 versionCode');
}
const source = readFileSync('AppScope/app.json5', 'utf8');
const config = JSON5.parse(source);
const app = config.app;
if (!app || typeof app.bundleName !== 'string') {
throw new Error('缺少 app.bundleName');
}
if (!/^([A-Za-z][A-Za-z0-9_]*\.)+[A-Za-z][A-Za-z0-9_]*$/.test(app.bundleName)) {
throw new Error('bundleName 格式不符合项目约定');
}
if (!Number.isSafeInteger(app.versionCode) || app.versionCode <= previous) {
throw new Error('versionCode 未高于已发布版本');
}
if (typeof app.versionName !== 'string' ||
!/^\d+\.\d+\.\d+$/.test(app.versionName)) {
throw new Error('versionName 不符合团队采用的三段式规则');
}
console.log(`预检通过:${app.bundleName} ${app.versionName} (${app.versionCode})`);
需要区分“团队规则”和“平台硬规则”。脚本里的三段式显示版本与包名正则是本案例的项目规范,不代表系统只允许这两种写法。它们的价值是把团队决定显式固定;一旦项目采用带预发布标识的版本号,只需更新校验规则即可。命令执行后若校验未通过,Node 进程会以错误退出,流水线便能在进入真正打包前停止。对于多模块工程,还要在后续阶段检查各模块目标和依赖解析,以免版本正确但产物缺失。
Debug 与 Release,不是改个文件名
DevEco Studio 和 Hvigor 允许选择 debug、release 等构建模式。两类产物可能采用不同的调试、混淆和签名配置,不能拿“打包产物的文件名里有 release”作为唯一依据。官方关于构建模式的文档明确区分工程级构建选项、模块级目标绑定以及优先级覆盖关系。这意味着同一个项目存在多层配置时,最终生效值需要结合模式、产品和目标一同审查,而不是只看某一行 JSON5。
对第一阶段的发布流程,我们建议把“选择 release 模式”和“检查 versionCode”分成两道门禁,再把证书、profile 的有效性作为独立安全门禁。尤其是签名材料,不应直接写在文章示例代码、仓库公共配置或流水线日志中。正式发包流程还涉及应用市场要求、签名证书关联、隐私合规与审核材料,这些事项不可能仅靠一段脚本代替。

即使发布校验脚本显示通过,也只能说明“这几项静态约束通过”,不能推断已经编译完成、签名有效或已在应用市场成功上架。把静态检查与真正的构建、安装、提交和审核分层报告,是避免自动化给人错误安全感的关键。图中流程正是这种分层门禁的设计示意:任一条件不满足即停止进入下一步,而不是带着问题生成一个看似完整的交付包。
让异常在最靠近原因的地方终止
发布前最常见的三类错误可以这样处理。第一类是版本回退:当前候选版本号低于或等于线上版本,直接拒绝打包并要求重新确定版本计划。第二类是环境漂移:构建环境选错产品或模式,在流水线显式检查选项,不允许以打包后的手工重命名补救。第三类是应用身份不一致:仓库的 bundleName 和应用市场已注册的身份无法匹配,要按应用注册信息追溯,而不是在不同人员电脑上做临时修补。
此外,配置文件本身也可能含有 JSON5 注释或尾随逗号,因此示例脚本使用专门的 JSON5 解析器,不简单把文件当作标准 JSON 去 JSON.parse()。对于一次构建同时生成多个目标的项目,单个 app.json5 预检还不够,后续需要覆盖多目标产物及其模块组合。构建脚本也可能通过 hook 在评估阶段修改配置,这种修改应纳入同样的审计与构建后核对流程,而不是绕过预检。
交付工程里,版本确认最好由发布负责人维护,开发者只提交预期的版本变更;静态门禁自动验证条件,真正签名权限只授予有权限的流水线。即使团队规模很小,也值得先建立清晰责任边界,因为权限与流程混在一起之后,最贵的成本不是写配置文件,而是追溯“谁在什么时候改变了发布行为”。
这一篇完成的是应用发布工程化的第一层:用单一来源记录版本,用静态门禁提前拒绝明显错误,并把构建模式与签名分开。下一篇将在同一个工程主线上处理多产品目标、构建输出目录与产物清单,继续复用本文的版本约定,而不是重新设计一套相互冲突的编号规则。
相关官方文档:
更多推荐



所有评论(0)