HarmonyOS 发布工程实践 02|Release 构建、签名与应用包交付校验【鸿蒙心迹】
权限和隐私材料都核对完了,很多项目会自然进入一种“应该可以提审了”的状态。结果轮到构建包时,开发电脑上跑得好好的版本,在 CI 里却找不到产物;或者本地拿错了 Debug 包;又或者构建包和开发者中心应用信息没有对齐,到了上传页面才发现还要重新处理签名。
这类问题麻烦的地方在于,它们经常不是代码 Bug,而是工程产物、版本身份和发布流程没有对上号。页面能运行只是开发的起点,发布需要另一套可核验的证据。
继续沿用上一期的中文 Demo “发布核查台”,这次不再重复权限扫描,而是给它增加“构建与提交”页面:记录提交来源、构建模式、版本号、APP 产物、文件指纹和 AGC 上传结果,让每次准备发布都有明确的交接单。

。
一、发布和安装不是同一个动作:先认清四种产物
在 HarmonyOS 工程里,经常能看到 HAP、HAR、HSP、APP。它们不是四种等价安装包。HAP 是应用功能模块安装包,HAR/HSP 分别对应不同的代码或资源共享形式;面向应用市场发布时,通常需要按官方要求构建包含应用模块信息的 APP 包。
还有一个容易混淆的概念:Debug/Release 是构建模式,不是 APP/HAP 的同义词。调试设备能安装某个 HAP,不等于这个产物满足应用市场提交要求。正式发布前要明确目标:哪个产品配置、哪个 API 目标、哪一套签名管理方式、最终上传哪个 APP 文件。
这次构建页先约定一个最小交接字段集:
commit:打包来源的代码提交号
bundleName:与开发者中心一致的应用包名
versionCode / versionName:待发布版本身份
buildMode:Release
artifact:本次构建生成的 .app 文件
sha256:构建产物内容指纹
signingMode:云管理 / 自有证书
uploadTarget:AGC测试 / 正式发布
其中 SHA-256 只是给团队内部确认“拿的是不是同一个文件”。它不能替代数字签名校验,也不能证明这个 APP 已通过应用市场审核。

把版本基线和工程入口绑定
我不赞成每个开发者都在自己电脑里修改一次版本号再交包。更稳的做法是让发布分支维护一套明确的版本基线,构建时从这套基线生成产物。提交号、产品配置和版本号应该共同进入构建记录,而不是构建完成以后靠人从聊天里把版本信息补全。
尤其有多产品、多模块的工程,某个模块可以单独编译成功,但完整 APP 的模块集合仍可能和预期不同。这个时候,“每个子模块都编译过”并不能代替“完整应用包已经核验”。最终上架的是整个应用的发布产物,责任也应该落到最终产物上。
二、HarmonyOS 7 / API 26 的签名流程,别照搬早期教程
这一步值得专门说清楚。官方发布应用文档区分了 SDK 26.0.0 之前和 26.0.0 及之后的流程。
较早版本通常要求开发者提前准备发布密钥、证书、Profile 等,在本地完成签名构建,再上传到 AppGallery Connect。在 API 26.0.0 及以后,DevEco Studio 支持先构建 APP,在上传到 AGC 时重新签名,可选自动生成的云管理证书,也可选择开发者自有证书。
所以这次工程里把“构建”和“最终发布签名”当成两个可核验阶段,而不是默认“本地有个 Release APP 就说明所有签名工作都结束了”。
在 DevEco Studio 里,构建入口可以按官方文档使用:
Build
→ Build Hap(s)/APP(s)
→ Build APP(s)
随后按上传流程选择 AppGallery Connect、Testing Only 或 Custom 等上传目标,核对应用关联关系,再选择自动或手动管理签名。上传用于测试和上传用于发布是不同选择,不要把测试上传完成理解成“已经提交正式审核”。
开发者选自动管理签名时,云管理证书由平台托管;如果团队有自身证书管理要求,也可以走手动管理流程。不同版本 DevEco 界面会有调整,按钮应以安装的实际版本与官方当前文档为准。

云管理证书省的是管理动作,不是发布责任
使用云管理证书确实可以减少本地保存私钥和手动轮换证书的成本。但团队仍需要确认:当前开发者账号是否能访问目标应用,是否选了正确的上传目标,证书管理方式是否符合公司流程,审核版本资料是否已经填好。自动化只是把部分操作交给平台,并不会自动判断这个版本是否应该公开发布。
官方的云管理证书说明也列出了有效期和轮换机制。实际项目不要自己维护一份永远不变的“证书还有效”的截图;每次正式提交前读取当次构建与平台反馈,才是可靠做法。若团队使用自有证书,需要把申请、授权、轮换、失效处理等职责落到具体负责人,不能只知道证书在某位同事电脑里。
我更希望在发布核查台里看到两列:“当前采用的签名管理方式”和“证书责任人或平台归属”。这比在文章里罗列一长串密码字段更有实际意义。
三、先把版本身份锁住,再开始打包
每次发布,最怕的是“构建完成以后才问这个版本号是多少”。包名、版本号、构建模式应该在构建前定下来,并由工程配置和团队记录共同约束。
例如 AppScope/app.json5 中保存应用基本身份:
{
"app": {
"bundleName": "com.example.publishcheck",
"versionCode": 1002000,
"versionName": "1.2.0",
"label": "$string:app_name",
"icon": "$media:app_icon"
}
}
这里的包名只是 Demo 使用的示例值;真正上架时,必须与开发者中心里关联的应用一致。旧包名改了,并不一定还能按原应用的升级路径发布。
工程级 build-profile.json5 的产品配置还会涉及 compileSdkVersion、compatibleSdkVersion、targetSdkVersion、signingConfig 等字段。Release 构建应该由工程实际的产品和构建模式决定,不要复制一段看起来差不多的配置以后,就把调试产物拿去上传。
为了方便团队复核,我会在“发布核查台”里做一个简单的版本身份卡:
| 字段 | 本次计划值 | 核对对象 |
|---|---|---|
bundleName | com.example.publishcheck | AGC 已关联应用 |
versionCode | 1002000 | 历史已发布版本 |
versionName | 1.2.0 | 版本说明和提审资料 |
buildMode | Release | 实际生成的构建产物 |
targetSdkVersion | 按实际工程填写 | SDK/设备兼容策略 |
版本身份一致了,再打包。这样即使某次构建失败,大家也知道失败属于哪一个确定的版本,而不是让“昨天那个包”和“今天这个包”混在一起。
四、签名配置不要写成公开教程里的明文密码
正式证书和调试证书解决的问题不同。调试签名用于开发验证,发布签名用于应用分发链路。使用自有证书时,相关的 .p12、.cer 和 .p7b 文件需要由有权限的人员维护,证书密码、密钥口令不能出现在文章截图、仓库或 CI 日志中。
DevEco Studio 中可以通过:
File
→ Project Structure
→ Project
→ Signing Configs
查看或配置签名方案。对于 targetSdkVersion 对应的新版本工具链,签名配置信息的管理位置也可能在 build-profile.json5 或 sign-config.json5 等配置中体现,要按当前版本的 Signing Configs 界面和生成文件检查,不要以一个旧版字段路径判断“签名一定没生效”。
实际排错时,我优先检查四件事:证书是否有效、Profile 是否与包名和权限相符、当前账号是否具有相应的应用操作权限、打包与上传时选择的是否为同一应用。任何一项不匹配,都不应该用“换个证书随便试试”来解决。
对于受限开放权限尤其要小心:调试成功不能说明发布 Profile 已获得对应权限;申请了不合适的受限权限,也可能在后续审核被要求整改。

五、CI 可以自动产出包,但要留下“它是怎么来的”
如果团队有两三个人同时打包,最先出现的问题通常不是构建失败,而是版本来源说不清。Release 流程最好只有一条固定命令路径,产物文件和构建信息一起归档。
Hvigor 的命令行可以从工程根目录调用仓库自带的 hvigorw。官方较早版本命令行文档给出的 APP 构建任务是 assembleApp,例如:
chmod u+x ./hvigorw
./hvigorw clean assembleApp --no-daemon
但任务名、实际产出路径和命令参数仍应以当前工程的 Hvigor 版本与任务列表为准。不要把某一版本教程中的输出路径写死成所有工程通用的路径。
构建完成以后,我会做一个最小的交接脚本。注意脚本只验证文件存在、大小非零、ZIP 容器是否可读取,并记录哈希;它不替代平台的格式和签名验证。
#!/usr/bin/env bash
set -euo pipefail
APP_FILE="${1:?请传入本次生成的 .app 文件路径}"
[[ -f "$APP_FILE" ]] || { echo "找不到 APP: $APP_FILE"; exit 1; }
[[ -s "$APP_FILE" ]] || { echo "APP 文件为空"; exit 1; }
unzip -t "$APP_FILE" >/dev/null
sha256sum "$APP_FILE" > "${APP_FILE}.sha256"
printf 'APP: %s\n' "$APP_FILE"
printf 'SIZE: %s bytes\n' "$(wc -c < "$APP_FILE")"
cat "${APP_FILE}.sha256"
如果运行环境没有 sha256sum,例如部分 macOS 开发机,可以改用 shasum -a 256。这段脚本的价值在于让交接变得确定:测试同事说“我验证的就是这个文件”,研发可以按哈希核对,不用靠文件名猜。

一次构建为什么要同时保存日志和符号表
Release 产物不是孤零零一个 .app 文件。构建日志记录了实际执行的任务与问题,符号表关联了运行后异常定位时需要的信息。假如应用上线后一周出现崩溃,而团队只保存最终 APP,编译机器上的中间资料已经清理,后续定位成本会明显上升。主题三才会细讲 DFX,但第二篇就应该建立归档意识。
我会要求同一版本的 APP、构建日志、符号表、版本交接单采用一致的版本身份。无论以后是内部测试发现问题,还是平台反馈某个构建参数需要调整,都能回到同一份资料。更换构建参数以后,产物哈希自然变化;也意味着旧版验证记录不能直接套用。
六、APP 包检查不能只盯着大小和签名
构建产物完整,只说明文件层面没有明显错误。提交前还要核查内部组成是否符合应用预期:是否包含正确的模块和资源,是否误带旧产物,版本身份是否与计划一致,发布模式下的调试开关是否关闭。
我会把核对项分成三档。
第一档:可由构建脚本立即完成。 文件存在、文件大小、哈希、产出时间、构建日志是否成功。这里最适合自动化。
第二档:工程配置与产物对照。 包名、版本、依赖模块、目标 API、构建模式、需要发布的资源是否符合预期。这一步需要结合工程配置和官方打包工具。
第三档:平台验收。 上传到 AGC 后的签名与包体校验、应用关联、权限声明、支持设备、版本要求等。这一步应以平台实际检测反馈为准。即便自己写的脚本全部显示绿色,也不能宣称“审核已通过”。
为了防止历史包混入,还可以为构建产物建立固定命名方式:
publishcheck-1.2.0-1002000-release.app
publishcheck-1.2.0-1002000-release.app.sha256
release-info.json
build.log
真正入库时再把 commit 和构建时间写入 release-info.json。一个提交对应一个产物集合,审计会简单很多。

把“能启动”验证改成真正针对 Release 的验证
Release 与 Debug 的差别不应只停留在一个下拉框。应用是否开启了代码混淆、资源压缩,是否去掉开发阶段的调试代码,某些仅在 Debug 环境暴露的问题是否被隐藏,都需要单独检查。特别是使用三方库和多模块依赖时,Release 构建成功不代表运行期一定没有问题。
我会选三类路径做最小回归:首次安装后打开首页、从旧版升级后读取存储数据、拒绝敏感权限以后继续执行基本功能。若项目还涉及文件分享、后台任务或复杂页面路由,再把这些高风险动作加入清单。每次回归记录设备系统版本和本次 APP 指纹,确保将来出现问题能复现对应环境。
对于多设备应用,还应确认声明支持的设备类型、屏幕大小和核心能力,在目标设备上真的可用。开发阶段某台设备上功能齐全,并不能代替整个发布范围内的兼容性检查。
七、上传到 AGC 时,最重要的是分清“重新签名”和“提交审核”
API 26 的上传流程把很多过去需要手动做的步骤收进了 DevEco Studio 与 AGC 的协同过程,但不能因此忽略关键确认项。
我会按下面顺序操作:
- 选择并构建当前产品的 Release APP;
- 在上传向导中确认正确的 AGC 应用、包名和目标用途;
- 选择云管理证书或手动管理签名;
- 完成上传与重新签名,检查平台返回的产物信息;
- 在开发者中心继续核对隐私说明、隐私标签、支持设备和版本资料;
- 需要正式发布时,再按版本发布流程提交审核。
自动管理签名有利于减少本地私钥维护成本,但并不等于可以忽视证书有效期、发布权限和团队成员账号的角色。手动管理签名更需要保持资料一致,尤其在多个项目和多个证书并存时,不要把“证书文件路径能读到”当成签名一定正确。
官方还支持在上传时管理构建版本、上传符号表等选项。符号表资料对后续 DFX 异常定位很重要,建议与 Release 版本一起归档,避免应用上线后需要分析崩溃,却发现构建产物和符号文件已经对不上。

细节:校验“谁做的”,不要只看“有没有做”
同一个检查动作由不同角色承担,证据也不一样。研发可以确认构建任务和源代码版本,测试负责 Release 设备回归,应用管理员确认 AGC 中的应用归属和上传结果,安全或合规人员检查相关资料。发布核查台把这些证据集中展示,但不应该让一个人代替所有角色点击完成。
对于上传后需要重新签名的流程,我还会记录上传时选择的目标方式以及平台返回的文件信息,并把它与本地构建产物对应起来。这样就能区分“上传前生成的原始文件”和“平台重签名后的最终分发文件”,避免团队仅凭文件名相似就认定两者字节完全一致。两者的哈希未必相同,但版本身份、目标应用和功能要求必须能够关联核对。
八、常见问题不要靠重打十次包来解决
上架前遇到问题,我建议先判断“出错发生在哪一层”。
| 现象 | 优先排查 | 不建议的做法 |
|---|---|---|
| 找不到 APP 文件 | 构建目标、模式、路径、日志 | 复制旧产物假装成功 |
| 上传提示包名不匹配 | AGC 应用绑定、bundleName | 随意修改包名碰碰运气 |
| 签名或 Profile 校验失败 | 云管理/手动签名方式、证书与 Profile 关系 | 反复换证书而不留记录 |
| 版本不符合要求 | 版本号与历史记录、Release 信息 | 用 Debug 构建冒充发布包 |
| 权限相关审核问题 | requestPermissions、业务场景、发布 Profile | 认为调试运行成功即可发布 |
| 上传后功能异常 | Release 差异、混淆、资源、权限 | 只复测 Debug 版本 |
在“发布核查台”里,每条问题都能关联到本次 release-info.json 和 APP 的 SHA-256。这样后续重新构建时,只要文件指纹变了,就必须重新说明本次提交改过哪些地方;不能把旧版测试结论直接沿用到新版产物。

发布回滚也需要提前想好
很多人只关心新版本怎样提交,却忘了问:如果 Release 版本一上线发现严重问题,我们怎么知道可以回到哪个版本?这里的“回滚”不意味着一定能在应用市场立即恢复旧包,而是团队要保留上一稳定版本的交付记录、版本差异、受影响功能和应急响应流程,具体操作取决于平台支持和当时的发布策略。
一份完整发布单至少可以说明:本次上线改了什么、哪个模块最容易受到影响、测试覆盖了哪些 Release 场景、出现问题时由谁判断暂停发布或提交修复版本。这样即使没有发生故障,团队也已经知道责任和决策链路,而不是临时拉群讨论谁有最终决定权。
再强调一点:包体校验不等于审核结果预测。构建脚本可以帮助我们检查文件是否损坏、是不是期望版本,但应用上架还涉及平台规则、隐私信息、开放能力授权和实际运行行为。工具不能“推测通过率”,更不能把检查项一律设为绿色。无论是研发、测试还是应用管理员,都应该知道每个绿色状态背后是谁、用什么方法确认过的。
九、发布链路要形成可交接的习惯,而不只是一次成功上传
这一篇最后留下一套比较实用的产物:构建配置记录、Release 交接卡、APP 文件及 SHA-256、版本身份对照表、AGC 上传回执、符号表归档和失败问题单。它们不一定全部自动生成,但至少能让接手的人知道本次版本究竟经历了什么。
我给团队定了一个简单的交接句式:
本次交付是
1.2.0 / 1002000的 Release APP,来源提交号已记录,哈希已存档,上传目标与签名管理方式已经核对;平台最终包体验证和提交审核状态,以 AGC 返回结果为准。
当“发布核查台”能把这句话里的每个信息都找到对应记录,构建流程就不再依赖“谁记得密码、谁电脑里还有旧证书、谁手上那个包更像最终版”。
下一篇会从真正上线后的质量问题继续往下走:当 Crash、Freeze 或异常出现时,怎样用 HiAppEvent、HiLog 把问题定位到具体版本和调用路径,而不是只收集一堆看不懂的日志。
官方资料与核对入口
更多推荐




所有评论(0)