HarmonyOS 应用开发之应用上架与分发详解

应用上架与分发一、引言上一篇文章完成了签名与打包本文继续回答打包之后怎么办如何把四个 HAP 送到不同设备用户手中。multi-short-video 没有真实的服务端与账号体系但它的多 HAP 结构恰好是理解 HarmonyOS 应用上架与分发机制的绝佳样本——一个应用、四种设备、四份产物、一套发布策略。上架不是简单地把包传到后台点发布它涉及应用信息维护、版本号规划、审核合规、渠道选择、灰度与回滚等一系列决策任何一个环节处理不当都可能造成审核驳回、用户流失甚至线上事故。本文结合 AGC 平台流程给出从应用创建、版本管理、审核到多渠道分发与灰度回滚的完整路径。二、AGC 应用创建与基础配置分发第一步是在 AppGallery Connect 创建应用。登录 AGC 控制台后选择我的应用 → 新建应用关键配置项如下配置项本工程建议值说明应用包名com.example.multishortvideo必须与AppScope/app.json5中 bundleName 一致应用名称多设备短视频与AppScope/resources/base/element/string.json中 app_name 保持一致应用分类影音娱乐影响应用市场类目与推荐位语言中文简体可多选对应工程内 zh_CN/en_US 资源发布国家/地区中国影响合规审核要求这里最容易踩的坑是包名不一致AGC 上创建的应用包名必须与工程AppScope/app.json5的bundleName完全一致且后续不可修改或修改成本极高一旦发现填写错误只能删除重建应用或申请修改。因此创建前务必先在工程里确认 bundleName再动手建应用。创建完成后需要维护应用的基础信息图标对应工程中AppScope/resources/base/media下的 layered_image 分层图标注意图标需要 512x512 且不能带圆角由系统统一裁切、截图真机截取的横竖屏截图建议包含关键页面、隐私政策链接与联系方式。对于多设备应用还需按设备类型分别上传对应 HAP 的说明与截图——直板机截图体现竖屏沉浸播放平板与电脑截图体现分栏布局智慧屏截图体现焦点导航手表截图体现精简交互四类截图素材可在工程screenshots/device目录基础上加工。截图规范也要留意不同设备类型对截图尺寸、数量有不同要求上传前对照 AGC 的说明逐项核对避免因截图不合格被驳回。三、版本管理与发布策略上架前先规划版本号。HarmonyOS 版本号体系由versionCode与versionName组成本工程定义如下// d:\HarmonyOS\WorkSpace\multi-short-video\AppScope\app.json5 { app: { bundleName: com.example.multishortvideo, vendor: example, versionCode: 1000000, versionName: 1.0.0, buildVersion: 1 } }versionCode是递增整数仅用于系统比较大小同一应用安装时后者必须更大versionName是面向用户的展示版本。多 HAP 场景下四个 HAP 的 versionCode 必须完全一致否则按设备安装时系统会因版本不一致而拒绝更新。本工程 versionCode 使用1,000,000这种大整数写法是给后续迭代留足余量如 1.0.0 → 1000000、1.0.1 → 1000001避免小步迭代很快撞上 2^31 上限或出现版本号回退的乌龙。建议版本策略为主版本迭代1.0.0 → 1.1.0新增功能四个 HAP 同步发布补丁版本1.1.0 → 1.1.1修复缺陷同步更新分设备独立小版本仅在确有差异时使用例如 TV 端单独修 Bug可只上传 TV 的新版本 HAP但 versionCode 必须高于所有设备上已安装的版本。在 AGC版本管理页面上传 HAP 后需填写版本更新说明建议按设备形态分别撰写突出该设备的体验改进并选择发布阶段内测Beta、正式Production、灰度分批放量。正式发布默认全量灰度发布则按比例放量常用于验证新版本在特定设备上的稳定性。需要特别提醒的是上传到 AGC 的 HAP 必须是使用发布证书签名的包调试证书签名的包在正式环境会安装失败这是提审时最高频的返工原因之一。四、应用审核要点华为应用市场对应用进行自动化与人工双重审核多设备应用重点核查以下方面权限合规逐项说明权限用途。本工程module.json5中声明的ohos.permission.DETECT_GESTURE属于受限权限审核时需提供使用场景说明若不需要应在上架包中移除。内容合规短视频应用需审核示例视频素材的版权与内容导向。本工程 rawfile 中的9_16.mp4、16_9.mp4等均为演示素材正式商用必须替换为自有版权内容且应说明视频内容的管理与举报机制。隐私政策应用内需提供可访问的隐私政策链接若应用有网络能力本工程无 INTERNET 权限则无需网络隐私声明需补充数据收集说明并做到声明什么就收集什么。多设备适配审核方会抽样在手机与平板真机安装验证需确保关键页面推荐流、评论、个人作品页无布局错乱、无黑屏、无功能缺失。版本一致性四份 HAP 的 versionCode 一致、签名证书一致、应用图标与名称一致。审核周期通常在 17 个工作日驳回后根据驳回原因修改可重新提审。建议把审核要点前置在提审前用上架自查清单见第六节逐项核对用一次通过降低迭代成本。对于示例项目最实际的准备工作是把 rawfile 中的演示视频、占位头像ic_user01.png等替换为合规素材否则即使代码质量再高也会卡在内容审核。五、多渠道分发与灰度回滚除华为应用市场外还可通过以下渠道分发渠道适用场景特点华为应用市场正式上架面向公众覆盖广、需审核、可灰度应用市场内测/众测小范围验证需审核但放量可控企业分发AppGallery Connect 企业证书企业内网员工免应用市场审核需企业实名认证本地安装hdc install开发调试不受渠道限制仅用于测试机企业分发是 B 端场景的重要补充使用企业证书签名的 HAP 可以绕过应用市场审核直接安装适合政府、企业内部使用但企业证书的申请要求更高需要企业资质认证且不能在未注册设备上安装适用于设备白名单场景。若产品面向大众消费者正规路径仍是应用市场。灰度与回滚是线上发布的安全网。推荐金丝雀策略先放量 1%5% 用户监控崩溃率与关键指标启动失败率、播放失败率无异常再逐步放量至 100%。回滚手段有两级一是 AGC 控制台将版本下线已安装用户不受影响二是通过推送高版本修复包覆盖因此务必保证versionCode单调递增为回滚后的修复版本留出空间。灰度期间要重点观察分设备指标——本工程四类设备硬件差异大手机端表现正常的版本在手表端可能因内存不足而频繁被杀灰度监控必须按 deviceType 维度拆分统计。灰度放量的节奏建议分三档1%探路重点看崩溃与安装失败率→ 10%功能验证看核心链路漏斗→ 50%稳定性验证看性能与耗电每一档停留 2448 小时并输出一份分设备数据对比。放量期间 AGC 会自动收集崩溃栈与性能数据务必在后台配置崩溃告警阈值如单设备类型崩溃率 0.5% 即暂停放量避免问题版本在放量窗口内扩大影响面。发布只是起点上线后的数据回收同样重要。建议在首个版本就埋好三类基础事件安装事件区分 HAP 类型验证四端安装是否符合预期、启动事件含启动耗时建立性能基线、核心功能事件视频起播成功率、评论打开率、作品页跳转成功率。没有这些基线数据后续每次发布的灰度判断都只能靠感觉无法量化。对示例工程而言至少要把日志体系common/multishortvideobase/src/main/ets/utils/Logger.ets中的关键路径日志与上报通道打通为灰度决策提供依据。六、上架前自查清单检查项本工程对应状态包名、签名与 AGC 配置一致AppScope/app.json5 发布证书必查四 HAP versionCode 一致各产品模块产物必查权限最小化、受限权限已说明module.json5 requestPermissions必查图标、截图、隐私政策齐备resources/base/media 截图必查演示素材版权确认resources/rawfile/*.mp4必查深色模式、多语言资源完整dark / zh_CN / en_US 目录建议发布说明按设备撰写AGC 版本管理建议崩溃率/启动耗时基线已建立线上监控建议自查清单建议沉淀为团队模板并在每次提审前由发布负责人逐项打勾。示例工程中尤其要注意前四项包名一致性、四端版本一致、受限权限说明、素材版权这四项占了多设备应用驳回原因的大头。七、总结与最佳实践上架与分发是把工程能力转化为用户价值的最后一步多设备应用尤其要警惕版本碎片化。核心经验一份签名、一套版本、四份产物、统一节奏。签名与包名全局唯一versionCode 全局单调递增并四端同步HAP 按 deviceTypes 各归其位发布节奏以设备形态为维度进行灰度与回滚。此外把上架自查清单沉淀为 CI 检查脚本自动比对四端 versionCode、自动校验签名指纹能显著降低临上架发现权限没删、截图没传的返工成本。对示例项目而言正式商用前务必替换演示视频与图标素材完成隐私合规评审再进入 AGC 提审流程——记住审核驳回一次迭代周期就拉长一周前置自查永远比事后补救划算。