鸿蒙 HarmonyOS 应用内测分发

蒲公英支持鸿蒙 App（.hap 文件）的上传、验证与分发，测试人员可便捷下载安装体验。本文介绍鸿蒙签名机制、在蒲公英的分发流程以及常见问题排查。

前置要求

• 一个华为开发者账号，可登录 AppGallery Connect。
• 已在 AppGallery Connect 中创建 发布证书（.p12），非调试证书。
• 已申请 指定设备发布 类型的 Profile（.p7b），其中包含测试设备的 UDID。
• 已使用上述 .p12 在 DevEco Studio 中完成 .hap 签名，得到 xxx-signed.hap 文件。

鸿蒙 App 与签名机制

HarmonyOS 是华为推出的多设备操作系统，支持手机、平板、可穿戴等终端。原生鸿蒙应用使用 ArkTS 编写，以 .hap 为打包格式，采用华为官方证书机制签名：

• .hap 是鸿蒙系统的可安装应用包（类似 Android 的 .apk）；
• 每个 .hap 必须经过签名才能在 HarmonyOS 设备上安装；
• 签名证书为 .p12 格式，来自华为开发者账号。

完整签名由三部分组成，三者必须完全一致 .hap 才能正确安装：

在蒲公英分发鸿蒙 App

上传已签名的 .hap 文件

请在本地使用开发者证书完成签名，上传至蒲公英的必须是 已签名 版本。上传前请确认：

• .hap 已通过签名工具（如华为官方 DevEco Studio）完成签名。正确签名后工具会生成名为 XXXX-signed.hap 的文件，具体方法请见 华为官方：编译打包应用；
• 为 .hap 签名所用的 .p12 证书，与后续要上传至蒲公英的 .p12 完全一致；
• 目前仅支持鸿蒙 .hap 文件，其他格式暂不支持。

填写 App 信息（可选）

为便于测试人员识别应用，可选填以下信息：

• 应用名称、版本号（蒲公英会自动解析并显示）
• 更新日志
• 应用截图
• 内测说明

以上信息将展示在应用的分发页面中。

上传 .p12 文件并设置密码

鸿蒙内测流程中，蒲公英会自动生成 manifest.json5 文件并签名以生成有效的安装元数据。因此需要向蒲公英提供与 .hap 同源的 .p12 证书及密码：

• .p12 可在华为 AppGallery Connect 的 证书、App ID 和 Profile 中下载；
• 此证书必须与签署 .hap 所用的证书一致，否则安装会失败；
• 蒲公英不对 .hap 本体进行签名，.p12 仅用于 manifest.json5 文件签名。

上传 P12 证书时，在弹出的浮层中输入证书密码与密钥别名。密钥别名默认为第一个；如果 P12 证书中包含多个密钥，请填写打包 App 时实际使用的那个别名。

为什么需要 .p12

这是华为规定的验证机制之一：HarmonyOS 设备在安装时会校验 manifest.json5 的签名，以确保应用来源可信。详见 华为官方文档。

获取分发链接，下载安装

完成上传后，蒲公英会自动生成下载链接与二维码：

• 可通过链接或扫码下载；
• 支持分享到微信、邮件、钉钉等渠道；
• 仅支持在 纯血 HarmonyOS NEXT 系统设备的浏览器中下载安装。

由于 .hap 的安装行为受系统安全策略限制，建议使用华为自带浏览器打开下载页面。

常见问题

上传 .hap 后安装失败，提示无法安装 "XXXXXX"

该问题通常与签名或配置不当有关，请按以下清单逐项检查。

签名相关

• .hap 必须是已签名的包，不能是未签名的。以 entry 模块为例，DevEco Studio 会在 /entry/build/default/outputs/default 下生成 xxx-signed.hap 与 xxx-unsigned.hap，应使用前者：

  

• 签名 .hap 时所用的 .p12，必须与上传到蒲公英的 .p12 为同一个；

• 上传 .p12 后请确认输入的密码是否正确（密码错误时平台会给出提示）；

• .p12 必须为 发布证书，不能使用调试证书。查看如何申请发布证书

Profile（.p7b）相关

• 签名 .hap 时所用的 Profile 必须为 指定设备发布 类型。若类型不匹配，上传后控制台会提示 Profile 类型错误。参见 申请指定设备发布 Profile：

  

• Profile 必须包含当前测试设备的 UDID。点击查看 UDID 获取方法

进一步排查

若以上均无问题，建议根据安装失败时出现的 错误码，前往 华为错误码目录 查询更具体的建议，或参见本页下方的 错误排查参考。

一个链接支持多人下载安装吗

支持。下载链接可分享给多个测试用户，平台同时提供安装统计、设备识别等功能。

平台是否会修改 .hap 文件

不会。蒲公英 不会修改 .hap 文件本体，仅对 manifest.json5 进行签名处理，以确保应用可正常安装。

是否支持 API 上传

支持。蒲公英提供 API 用于上传 App 文件。对于鸿蒙 App，首个 App 上传完成后，还需调用 API 上传 .p12 文件。详见 API 文档。

是否支持上传 .hsp 文件

支持。请先上传 .hap 文件，之后可在 应用管理 中找到上传 .hsp 的入口。

• 仅检测到需要 .hsp 依赖的 App 才开放此入口，并会提示所需的 .hsp 数量；
• 目前仅支持 内部 .hsp 依赖，暂不支持外部依赖。

暂不支持的场景

• .app 格式的文件；
• 在同一应用中上传多个 .hap 文件；
• 鸿蒙元服务。若下载到桌面后点击图标即消失，很可能是元服务，当前不支持。

错误排查参考

常见错误码

其它常见错误提示

更多参考

• 华为官方文档：HarmonyOS 应用内测分发指南