HarmonyOS 原生应用上架全流程：从 HAP 构建到 AGC 审核的实战路线

摘要

本文围绕 HarmonyOS 原生应用从本地构建、HAP 产物、签名证书、发布 Profile、真机验证、AppGallery Connect 资料填写到审核驳回修复的全流程，构建一套面向开发者和自动化发布工具的上架检查方法。文章以"工具类应用首次上架"为案例，讲解版本冻结、权限说明、隐私政策、测试账号、截图素材、构建日志、审核反馈分类和重提策略。

关键词：HarmonyOS NEXT；HAP；AppGallery Connect；发布证书；发布 Profile；DevEco Studio；hvigor；flutter build hap；隐私政策；审核修复

图 1 HarmonyOS 原生应用上架流程总览

文章目录

为什么上架比打包更容易出错
上架前先冻结版本范围
HAP 产物不是唯一交付物
签名证书与 Profile 的关系
DevEco Studio 与命令行构建
Flutter OHOS 项目的特殊注意点
真机验证要覆盖权限和异常
AGC 资料不是文案填空
隐私政策要和权限声明一致
测试账号和审核说明要可复现
代码示例一：发布前检查模型
代码示例二：PowerShell 构建前检查
代码示例三：审核资料缺失扫描
自动化上架前检查流水线
审核驳回如何分类处理
常见失败清单
本文小结
上架能力与风险矩阵
参考资料

1. 为什么上架比打包更容易出错

很多开发者以为 HAP 打出来就离发布不远了，但真正的上架问题往往出现在签名、权限、隐私、截图、测试账号和审核复现路径上。构建成功只说明工程能产生产物，不代表产物能被用户安全、稳定、合规地使用。

高质量的上架流程应该把"构建、验证、资料、审核"放在同一个闭环里，而不是开发完成后临时补材料。

2. 上架前先冻结版本范围

上架前建议冻结版本号、包名、权限、核心功能、截图页面和隐私政策。任何临时改动都可能导致截图与实际不一致、权限说明不一致、测试账号不可用或审核人员无法复现。

如果团队多人协作，最好建立发布分支或发布目录，把这一次要提交的 HAP、截图、说明文档、隐私链接和变更记录放在一起归档。

3. HAP 产物不是唯一交付物

HAP 是软件包，但不是全部交付物。AGC 还需要应用名称、分类、简介、图标、截图、版本说明、权限说明、隐私政策、测试账号和审核备注。

自动化工具可以先检查这些材料是否缺失，再决定是否允许进入上传和提交步骤。

4. 签名证书与 Profile 的关系

发布证书、发布 Profile、包名和权限声明必须互相匹配。常见问题包括证书不对应、Profile 类型不对、包名变更后未重新生成 Profile、权限申请与实际功能不一致。

签名问题的麻烦在于：有时构建能过，但安装失败；有时安装能过，但审核阶段因为包名、签名或权限说明不清被拦下。

图 2 HAP、证书与 Profile 的关系

5. DevEco Studio 与命令行构建

DevEco Studio 适合可视化配置签名、调试和检查工程；命令行适合自动化构建、流水线和重复发布。两者不要互相割裂，最好让命令行使用同一套 SDK、Node、JDK、hvigor 和签名配置。

如果本地有多套 SDK 或多个 Java 版本，建议在构建脚本里显式设置路径，避免"开发机能打包，自动化环境打不了"的情况。

6. Flutter OHOS 项目的特殊注意点

Flutter OHOS 项目通常需要关注 flutter_ohos SDK、DevEco Studio 工具链、hvigor、ohpm、OpenHarmony SDK 和签名配置。命令行执行 flutter build hap 前，要确认 PATH 中优先使用 DevEco Studio 自带工具链。

如果出现 hvigorw 找不到、JDK 不匹配、ohpm 不可用、签名配置缺失等问题，应先修环境，再看业务代码。

7. 真机验证要覆盖权限和异常

真机验证不能只看启动页。至少要覆盖首次启动、登录或游客路径、核心功能、权限弹窗、权限拒绝、弱网、后台恢复、退出重进和卸载重装。

如果应用需要审核账号，要确认审核账号在全新设备上可以登录，并且不会被验证码、设备锁、实名或地区限制卡住。

8. AGC 资料不是文案填空

AGC 资料是审核人员理解应用的入口。应用简介要准确，截图要展示真实页面，版本说明要说明本次变更，审核备注要告诉审核人员怎么进入核心功能。

如果应用功能依赖服务端开关、测试账号、地区、权限或特殊设备，必须在审核说明中写清楚。

图 3 AGC 上架资料能力地图

9. 隐私政策要和权限声明一致

隐私政策不是一段通用模板。它应该说明应用收集哪些数据、为什么收集、如何使用、保存多久、是否共享、用户如何撤回授权。

权限声明与隐私政策要保持一致。例如申请定位权限，就要说明定位用于什么场景；申请相机权限，就要说明拍照或扫码用途。

10. 测试账号和审核说明要可复现

审核账号要稳定可用，密码不要临时过期，登录后不要立即要求绑定手机、实名认证或输入验证码。审核说明应包含入口路径、账号密码、需要开启的权限、预期看到的页面。

如果应用没有账号体系，也要说明如何体验核心功能，避免审核人员停在空白页或引导页。

11. 代码示例一：发布前检查模型

发布工具可以把上架前检查抽象成 ReleaseCheckItem，再统一生成通过、警告、阻断三类结果。

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type CheckLevel = 'pass' | 'warning' | 'blocker' interface ReleaseCheckItem { id: string name: string category: 'build' | 'signing' | 'privacy' | 'metadata' | 'review' level: CheckLevel message: string fixHint?: string } const profileCheck: ReleaseCheckItem = { id: 'signing.profile.exists', name: '发布 Profile 检查', category: 'signing', level: 'blocker', message: '未找到发布 Profile，不能进入 AGC 上传步骤', fixHint: '在 AppGallery Connect 或 DevEco Studio 中生成发布 Profile' } |

12. 代码示例二：PowerShell 构建前检查

Windows 自动化构建前，先检查 Flutter、hvigor、ohpm 和工程目录，避免构建到一半才发现环境缺失。

|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| $project = "C:\\Users\\26444\\CSWJ\\my_app01"$ checks = @("flutter", "hvigorw", "ohpm") foreach ( $cmd in$ checks) { $hit = Get-Command$ cmd -ErrorAction SilentlyContinue if (-not $hit) { throw "缺少命令：$ cmd，请先检查 DevEco / Flutter OHOS 环境变量" } } if (-not (Test-Path " $project\\pubspec.yaml")) { throw "不是 Flutter 项目：$ project" } Set-Location $project flutter build hap --release |

13. 代码示例三：审核资料缺失扫描

提交前可以用结构化清单检查截图、隐私政策、测试账号和审核备注。真正上传前仍应人工确认内容真实性。

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| interface ReviewMaterial { appName: string iconReady: boolean screenshots: string\[\] privacyUrl?: string testAccount?: string reviewNote?: string } function scanMaterial(m: ReviewMaterial): string\[\] { const missing: string\[\] = \[\] if (!m.appName) missing.push('应用名称') if (!m.iconReady) missing.push('应用图标') if (m.screenshots.length < 3) missing.push('至少 3 张核心截图') if (!m.privacyUrl) missing.push('隐私政策链接') if (!m.reviewNote) missing.push('审核说明') return missing } |

14. 自动化上架前检查流水线

自动化的价值不是绕过审核，而是把重复检查变成稳定流程。建议至少自动检查包名、版本号、产物大小、签名材料、权限声明、截图数量、隐私链接和测试账号说明。

图 4 自动化上架前检查流水线

15. 审核驳回如何分类处理

审核驳回后，不要只改当前问题。应先记录驳回原文、截图、提交版本和复现路径，再分类判断是功能不可用、权限说明不足、隐私政策不一致、截图不符、测试账号不可用还是资质材料缺失。

每一次驳回都应该沉淀为下一次发布前的检查项。这样几轮之后，团队会形成自己的鸿蒙上架知识库。

图 5 审核驳回修复闭环

16. 常见失败清单

发布 Profile 和包名不匹配，导致安装或审核失败。
权限申请过多，但隐私政策和审核说明没有解释用途。
截图展示的是旧版本页面，与当前 HAP 不一致。
测试账号需要验证码或地区限制，审核人员无法登录。
应用首次启动卡在空白页、权限弹窗或网络错误页。
版本号没有递增，或版本说明没有说明本次变化。
服务端关闭测试环境，审核时核心功能无法复现。

17. 本文小结

HarmonyOS 原生应用上架不是"打一个 HAP 然后上传"，而是一套工程化发布流程。开发者需要同时管理构建环境、签名材料、Profile、真机验证、隐私说明、AGC 资料和审核反馈。

如果把每一步都做成可检查、可复盘、可沉淀的流程，上架就会从临时手工活变成稳定发布能力。

18. 上架能力与风险矩阵

|------------|-------------|----------------------------------|
| 环节 | 业务价值 | 主要风险与控制 |
| HAP 构建 | 形成可上传的软件包 | 工具链不一致；固定 SDK、JDK、Node、hvigor 版本 |
| 发布签名 | 证明应用来源可信 | 证书/Profile 不匹配；发布前做签名链路检查 |
| 真机验证 | 提前发现安装和运行问题 | 只测启动页；覆盖权限、弱网、卸载重装 |
| AGC 资料 | 帮助审核理解应用 | 截图/说明不一致；材料随版本同步更新 |
| 隐私政策 | 降低合规风险 | 模板化说明；按权限逐项解释用途 |
| 审核修复 | 缩短重提周期 | 只修表面；沉淀驳回知识库 |