《鸿蒙上架：从签名到 AppGallery》
要点
鸿蒙应用上架的链路是：备齐签名三件套 → release 出 .app 包 → AppGallery Connect（AGC）建应用、传包、提审。步骤不多，但材料之间互相咬合：包名差一个字母，Profile 就签不上去；证书过期没续，审核过了也发不了版。这篇按我给一个工具类应用走完全流程的顺序写。口径：HarmonyOS NEXT 5.0.0（API 12）作为打包目标，系统侧 5.0.4（API 16）已于 2025-03-27 Release，DevEco Studio 5.0.x。
为什么按 API 12 出包：NEXT 5.0.0（API 12）是 NEXT 系的基线，设备覆盖面最大，三方 SDK 的适配说明也多以此为准。追新 API 的项目可以把 compileSdkVersion 抬到 5.0.4（API 16），但测试矩阵与材料要跟着动——上架这篇不背这个变量。本文不做：调试签名排错（自动签名一键搞定，翻车了看日志）、多产品形态（product）、内购与账号服务开通。
整条链路的时间体感：三件套首次办最费时，AGC 网页上点来点去加等证书生效，半天量级；签名配置与出包本身几分钟，卡住时基本都是路径与密码抄错；AGC 填应用信息最琐碎——图标、截图、隐私声明、备案号一样不能少，认真备齐也要半天。第一次走全程预留一两天宽限，第二次起半天能走完（证书续期另算）。
三件套：密钥库、证书、Profile
发布签名三件材料，生成顺序有讲究：
- .p12 密钥库：DevEco Studio 菜单 Build → Generate Key and CSR，新建密钥库、设密码、导出密钥，同时产出 .csr 证书请求文件；
- .cer 发布证书：AGC 控制台 → 证书/APP ID/Profile → 证书，上传 .csr 换取发布证书。发布证书按账号维度管理，注意有效期，到期要续办并重新签名出包；
- .p7b 发布 Profile：AGC 里新建 Profile，绑定 APP ID（即包名）与发布证书，导出 .p7b。
咬合关系一句话：Profile 锁包名与证书，证书锁账号，密钥库锁私钥——链上任何一环对不上，出包直接报签名错误。所以密钥库文件和密码必须当天归档进密码管理器：丢了，证书链就断了，只能推倒重来。调试侧的自动签名（File → Project Structure → Signing Configs 勾选 Automatically generate signature）出的是调试证书与调试 Profile，和发布三件套不通用——拿调试包提审，材料校验第一关就过不去。
三件材料各自的分工
三个文件的角色容易混，用一句话钉住：.p12 是你手里的私钥容器（谁有它谁能签名），.cer 是账号侧的公钥凭证（AGC 靠它确认”这个私钥属于这个账号”），.p7b 是授权书（把包名、证书、权限范围绑在一起）。签名时三方对齐才通过——所以 .csr 必须从 .p12 生成再上传，拿别人的 .csr 换回来的 .cer 和你的私钥对不上，签名必败。storePassword 与 keyPassword 分别锁密钥库与库里那把 key，两个密码可以不同，归档时都记上。证书到期续办流程原样再走一遍：新的 .csr、新的 .cer、新的 Profile，出包重签，用新版本覆盖安装即可。
签名配置与出包
发布签名写进 build-profile.json5 的 signingConfigs。密码别明文进仓库，用 DevEco 的存储机制或环境变量注入：
"signingConfigs": [
{
"name": "release",
"material": {
"storeFile": "./sign/release.p12",
"storePassword": "******",
"keyAlias": "publish",
"keyPassword": "******",
"signAlg": "SHA256withECDSA",
"certpath": "./sign/release.cer",
"profile": "./sign/releaseProfile.p7b"
}
}
]出包两条路，产物相同：
# DevEco Studio：Build → Build APP(s)/HAP(s) → Build APP(s)
1. 命令行（CI 用）：
hvigorw assembleApp -p buildMode=release产物在 build/default/outputs/default/ 下，扩展名 .app——App Pack，里面按设备形态装着 HAP，AGC 拿到后自动拆分分发。assembleApp 与 assembleHap 的区别：前者出上架用的 .app，后者只出 HAP。验收三点：
- 包名与 AGC 创建的应用完全一致（bundleName 逐字符核对）；
- versionCode 比线上版本大，覆盖安装才有效；
- 确认签的是发布 Profile——报”证书或 Profile 不匹配”时，先查 material 路径与密码。
上 AGC 前先真机冒烟：hdc install 装上 release 包，走一遍核心路径——启动、登录态、关键页面、退出重进。签名问题（Profile 与包名不符、证书链断裂）在真机安装这一步最先暴露，别等到 AGC 解析失败再回头查。冒烟清单同样适用于驳回后重提的版本——改了什么就多验什么，驳回修复最怕引入新问题。hdc 在 DevEco Studio 的 toolchains 目录里，PATH 配上就能直接用。
AGC 建应用与提审
顺序：AGC 控制台 → 我的项目 → 创建项目 → 创建应用，包名填进工程的 bundleName；然后在”我的应用”里补全应用信息——名称、图标、简介、分类、截图、隐私声明 URL、版本说明。分类与资质提前查：工具、效率这类常规类目材料简单；新闻、社交、直播等特殊类目要对应资质，AGC 在选分类时会提示——选类目别只图流量大的词，资质补不齐会被整体卡住。图标与名称定了再建应用：AGC 里改包名等于推倒重来，改图标名称反而只是更新材料。国内上架还有一道硬门槛：App 备案（工信部备案），备案号要填进 AGC 应用信息对应字段，2023 年起新应用上架国内应用市场都需要。
版本发布页上传 .app，AGC 解析后按设备形态拆分，确认版本信息无误就提交审核。审核状态在页面上推进（新建 → 审核中 → 已发布/驳回），时长以页面提示为准；驳回会附原因列表，逐条对应修复再提。我两次提审分别在一个和两个工作日内出结果，驳回一次、过一次——驳回的原因正是下一节清单里的第一条。
版本管理纪律
三条纪律立在前头：versionCode 只增不减，每次提审都比上一次大，被驳回后修复重提也别用更小的号；versionName 给人看，随手和版本说明对齐；已发布版本没有”回滚”按钮，线上出问题只能用更高 versionCode 的新版本覆盖——所以出包前的真机冒烟不是仪式感，是唯一防线。版本说明认真写：审核员会看，用户更新弹窗里也会看，”修复已知问题”这种话等于没写。
隐私合规清单
提审前逐项打勾，这份就是我的自查表。清单里最容易被轻描淡写的是权限：动手前先把 module.json5 里 requestPermissions 全量导出，逐个问”这个权限对应哪个功能场景”，答不上来的直接删权限而不是补理由——权限越少，审核越顺。
- 首次启动先弹隐私同意，同意前不申请任何敏感权限、不上报任何数据——审核员会冷启动验这个时机；
- 隐私政策 URL 公网可达，页面内含应用名称、开发者主体、收集的数据类型与各权限用途；
- module.json5 的 requestPermissions 里，每个敏感权限有 usedScene 与 reason，文案具体到”用于扫描二维码”，不写”提升用户体验”这类空话；
- 权限最小化：申请的每个权限都能在功能里指出对应场景；ACL 受限权限（如后台定位）按 AGC 要求提交用途说明；
- 实际采集的数据类型与隐私声明一致——接了个崩溃上报 SDK 就得声明设备信息收集，这是最容易漏的一条；
- App 备案号与备案主体一致；
- 年龄分级、内容自审按类目如实填写。
常见驳回原因
- 隐私政策链接打不开，或页面里搜不到应用名——主体与应用对不上；
- 权限理由笼统或与功能不符：截图里看不到申请该权限的使用场景；
- 截图与实际界面不符（拿设计稿凑数）；
- 包名与签名材料不一致，安装校验失败；
- versionCode 未递增，或测试设备系统低于兼容口径导致装不上；
- 功能不完整：空页面、按钮无响应、明显网页套壳痕迹；
- 图标或名称含侵权、模仿元素；
- 首启没弹隐私同意，或同意弹窗出现前权限已被申请——合规时机的硬伤。
这些驳回项的共同点：都是审核员从材料里看不到或对不上的东西。合规清单和驳回清单在提交前各过一遍，绝大多数驳回可以在出门前拦住。
验收清单
- Build APP(s) 或 hvigorw assembleApp 出包成功，.app 文件存在且为发布签名；
- AGC 上传解析通过，设备形态拆分正常；
- 应用信息、隐私声明、备案字段齐全，合规清单全勾；
- 提审状态推进到已发布，或驳回项逐条对应到修复动作；
- 签名三件套与密码已归档进密码管理器。
这份清单第二次走流程时可以压缩：三件套已归档、AGC 应用已建，每次发版真正要过的只有出包、版本号、更新说明与隐私声明的增量核对。把核对项固化成仓库里的 checklist 文件，谁发版谁打勾，交接也不用靠口口相传。
上架前的最后一轮质量检查（单元测试与 Profiler 体检）见测试入门，工程本体从实战篇来。签名材料办完当天就归档——明年续证书的时候，你会感谢现在的自己。
本文数据核对时间：2025-04-11：HarmonyOS NEXT 5.0.0（API 12）为打包目标口径；系统版本与 API 对应关系为 5.0.1→API 13、5.0.2→API 14、5.0.3→API 15、5.0.4→API 16，5.0.4（API 16）Release 于 2025-03-27 发布；DevEco Studio 5.0.x；签名材料与 AGC 提审流程以华为开发者官网当前文档为准。