摘要本文围绕 HarmonyOS 原生应用从本地构建、HAP 产物、签名证书、发布 Profile、真机验证、AppGallery Connect 资料填写到审核驳回修复的全流程构建一套面向开发者和自动化发布工具的上架检查方法。文章以“工具类应用首次上架”为案例讲解版本冻结、权限说明、隐私政策、测试账号、截图素材、构建日志、审核反馈分类和重提策略。关键词HarmonyOS NEXTHAPAppGallery Connect发布证书发布 ProfileDevEco Studiohvigorflutter build hap隐私政策审核修复图 1 HarmonyOS 原生应用上架流程总览文章目录1. 为什么上架比打包更容易出错2. 上架前先冻结版本范围3. HAP 产物不是唯一交付物4. 签名证书与 Profile 的关系5. DevEco Studio 与命令行构建6. Flutter OHOS 项目的特殊注意点7. 真机验证要覆盖权限和异常8. AGC 资料不是文案填空9. 隐私政策要和权限声明一致10. 测试账号和审核说明要可复现11. 代码示例一发布前检查模型12. 代码示例二PowerShell 构建前检查13. 代码示例三审核资料缺失扫描14. 自动化上架前检查流水线15. 审核驳回如何分类处理16. 常见失败清单17. 本文小结18. 上架能力与风险矩阵19. 参考资料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 | blockerinterface ReleaseCheckItem {id: stringname: stringcategory: build | signing | privacy | metadata | reviewlevel: CheckLevelmessage: stringfixHint?: 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 SilentlyContinueif (-not $hit) {throw 缺少命令$cmd请先检查 DevEco / Flutter OHOS 环境变量}}if (-not (Test-Path $project\pubspec.yaml)) {throw 不是 Flutter 项目$project}Set-Location $projectflutter build hap --release13. 代码示例三审核资料缺失扫描提交前可以用结构化清单检查截图、隐私政策、测试账号和审核备注。真正上传前仍应人工确认内容真实性。interface ReviewMaterial {appName: stringiconReady: booleanscreenshots: string[]privacyUrl?: stringtestAccount?: stringreviewNote?: 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 资料帮助审核理解应用截图/说明不一致材料随版本同步更新隐私政策降低合规风险模板化说明按权限逐项解释用途审核修复缩短重提周期只修表面沉淀驳回知识库
HarmonyOS 原生应用上架全流程：从 HAP 构建到 AGC 审核的实战路线
发布时间：2026/7/30 3:23:10
摘要本文围绕 HarmonyOS 原生应用从本地构建、HAP 产物、签名证书、发布 Profile、真机验证、AppGallery Connect 资料填写到审核驳回修复的全流程构建一套面向开发者和自动化发布工具的上架检查方法。文章以“工具类应用首次上架”为案例讲解版本冻结、权限说明、隐私政策、测试账号、截图素材、构建日志、审核反馈分类和重提策略。关键词HarmonyOS NEXTHAPAppGallery Connect发布证书发布 ProfileDevEco Studiohvigorflutter build hap隐私政策审核修复图 1 HarmonyOS 原生应用上架流程总览文章目录1. 为什么上架比打包更容易出错2. 上架前先冻结版本范围3. HAP 产物不是唯一交付物4. 签名证书与 Profile 的关系5. DevEco Studio 与命令行构建6. Flutter OHOS 项目的特殊注意点7. 真机验证要覆盖权限和异常8. AGC 资料不是文案填空9. 隐私政策要和权限声明一致10. 测试账号和审核说明要可复现11. 代码示例一发布前检查模型12. 代码示例二PowerShell 构建前检查13. 代码示例三审核资料缺失扫描14. 自动化上架前检查流水线15. 审核驳回如何分类处理16. 常见失败清单17. 本文小结18. 上架能力与风险矩阵19. 参考资料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 | blockerinterface ReleaseCheckItem {id: stringname: stringcategory: build | signing | privacy | metadata | reviewlevel: CheckLevelmessage: stringfixHint?: 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 SilentlyContinueif (-not $hit) {throw 缺少命令$cmd请先检查 DevEco / Flutter OHOS 环境变量}}if (-not (Test-Path $project\pubspec.yaml)) {throw 不是 Flutter 项目$project}Set-Location $projectflutter build hap --release13. 代码示例三审核资料缺失扫描提交前可以用结构化清单检查截图、隐私政策、测试账号和审核备注。真正上传前仍应人工确认内容真实性。interface ReviewMaterial {appName: stringiconReady: booleanscreenshots: string[]privacyUrl?: stringtestAccount?: stringreviewNote?: 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 资料帮助审核理解应用截图/说明不一致材料随版本同步更新隐私政策降低合规风险模板化说明按权限逐项解释用途审核修复缩短重提周期只修表面沉淀驳回知识库
