鸿蒙 HarmonyOS App 如何内测分发

随着鸿蒙系统（HarmonyOS）生态的快速发展，越来越多的开发者开始构建纯血鸿蒙应用（HarmonyOS Native）。为支持开发者高效完成内测流程，蒲公英内测分发平台现已全面支持鸿蒙 App（.hap 文件）的上传、验证与分发，帮助测试人员便捷下载安装体验。

一、鸿蒙 HarmonyOS App 简介

HarmonyOS 是华为推出的新一代多设备操作系统，支持手机、平板、可穿戴等多种终端。开发者通过 ArkTS 编程语言构建的原生鸿蒙应用，以 .hap 为打包格式，并采用鸿蒙官方提供的证书机制进行签名和验证。

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

签名分为三部分：

对 hap 本体签名（用户在本地完成，蒲公英不参与）；
对 p7b 文件签名（即 Profile 文件） (用户在本地或华为 AppGallery Connect 完成，蒲公英不参与)
对 manifest.json5 文件签名（用户需将 p12 文件上传到蒲公英平台后，蒲公英平台完成此步骤）；

注意：以上三部分签名需要完全一致才可正确安装 App

二、在蒲公英平台分发鸿蒙 App 的操作流程

第一步：上传已签名的 `.hap` 文件

用户需在本地使用开发者证书完成 .hap 文件的签名。上传至蒲公英的平台版本必须为已签名版本。

上传前请确保：

.hap 文件已使用签名工具签名，如华为官方开发工具 DevEco-Studio，具体方法请见华为官方文档：编译打包应用，正确签名后，工具一般会生成名称为 XXXX-signed.hap 的文件；
对 .hap 签名所用的 .p12 证书与即将上传至蒲公英平台的 .p12 文件完全一致；
目前支持鸿蒙的 .hap 文件。

准备上传

第二步：填写 App 信息（可选）

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

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

这些信息将在分发页面中显示，提升专业度与可读性。

填写App信息

第三步：上传 `.p12` 文件并设置其密码（用于 manifest.json5 签名）

在鸿蒙内测流程中，蒲公英平台会自动生成内测分发所需的manifest.json5文件，且需对 manifest.json5 文件进行签名，以生成有效的安装元数据。因此，开发者（您）需向蒲公英平台提供与 .hap 同源的 .p12 证书及其密码：

.p12 证书您可以在华为开发者平台的 AppGallery Connect 中的 “证书、APP ID和Profile” 中进行下载；
此证书必须与您在第一步中上传的 .hap 文件本身签名使用的证书一致，否则会导致安装失败；
蒲公英不会对 .hap 本体进行签名，仅用于 manifest.json5 文件签名。

上传p12证书

上传 P12 证书时，请在弹出的浮层输入证书密码及密钥别名，密钥别名默认为第一个密钥别名，如果 P12 证书里有多个密钥，请输入打包 App 时使用的密钥别名。

输入密码及别名

为什么需要 `.p12`？

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

第四步：获取分发链接，下载安装

完成上传后，蒲公英会自动生成一个可供下载的链接和二维码：

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

目前 .hap 文件的安装行为受到系统安全策略限制，推荐使用华为自带浏览器打开下载页面。

三、常见问题答疑

Q1：上传 `.hap` 后安装失败，提示无法安装“XXXXXX”？

出现此问题，通常与签名或配置不当有关。请逐项检查以下内容：

签名相关检查

.hap 必须为已签名的包，不能为未签名的包。例如，对于 entry 模块 DevEco Studio 会在 /entry/build/default/outputs/default 目录下生成 xxx-signed.hap 和 xxx-unsigned.hap 的包，此时您应该使用 xxx-signed.hap 这个包；
签名 .hap 文件时使用的 .p12 文件，必须和您在前述步骤中上传到蒲公英平台的 .p12 文件为同一个；
在蒲公英平台上传 .p12 文件后，是否输入了正确的密码。目前，如果您输入了不正确的密码，蒲公英平台会进行提示；
.p12 必须为 发布证书，不能使用调试证书。查看如何申请发布证书

发布证书

Profile (.p7b) 检查

签名 .hap 文件时所用的 Profile 类型必须为 指定设备发布 类型。目前，如果您上传了安装包后，如果安装包中的 Profile 文件类型如果不是 指定设备发布 类型时，蒲公英平台的控制台中会显示 Profile 类型错误。具体请查看文档申请指定设备发布Profile

指定设备发布

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

进一步排查

如果以上均无误，建议根据安装失败时出现的 错误码，前往华为错误码目录进行查询，以获得更具体的排查建议。

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

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

Q3：平台是否对 `.hap` 文件做修改？

不会。蒲公英平台不会修改 .hap 文件本体，仅用于对 manifest 文件进行签名处理，确保安装成功。

Q4：是否支持 API 上传？

支持。蒲公英提供了 API 用于上传 App 文件，另外，对于鸿蒙 App 来说，首个 App 上传完成后，还需调用 API 上传 p12 文件。具体可见 API 文档

Q5：是否支持上传 hsp 文件？

支持。您需要先上传 hap 文件，之后在 应用管理 中可以找到上传 hsp 文件的入口。只有检测到需要上传 hsp 文件的 App 才可以上传，并且提示上传 hsp 的数量。目前只支持内部 hsp 依赖，暂不支持外部依赖。

上传 hsp 依赖

Q6：是否支持上传 .app 格式文件？

目前还不支持。

Q7：是否支持上传多个 .hap 文件？

目前还不支持。

Q8：是否支持鸿蒙元服务？

目前还不支持。下载到桌面后点击图标就消失，可能是鸿蒙元服务，目前不支持

四、更多参考

如需了解鸿蒙官方对内测分发的完整说明，请参考：华为官方文档：HarmonyOS 应用内测分发指南

常见错误码及解决办法

错误码	说明
10003	上传的 P12 文件证书密钥与 hap 签名不匹配，可先检测 p12 证书是否上传正确
10021	设备 udid 不在 p7b 描述的范围里，或者签署 p7b 的证书和签署 app 包的证书
17700018	依赖的模块不存在，查看是否上传所需要的 hsp 依赖
17700019	p12和安装包的签名秘钥不一致，重新上传 P12 证书，输入证书密码及签名 App 时使用的密钥别名
17700054	大概率是ACL权限的原因，需要申请权限后重新创建Profile以及重新生成p12
17700073	手机上存在相同包名或者卸载不完全的应用
17700015	多个HAP配置信息不同导致，要尝试 buildOption下的debuggable:false 去掉再重试

其它常见错误

错误提示	说明
上传P12证书时密码错误	需要输入生成p12时设置的密码查看文档
点击图标后提示应用已过期	证书过期或者测试授权到期导致的
打开图标后出现闪退	证书原因或APP本身bug
下载页面提示未签名	请到 App 概述页面上传 P12 证书文件查看文档
平台提示证书不匹配	p12的公钥与 hap 签名证书的公玥不匹配，重新上传 P12 文件或查看 P12 是否有多个key 查看文档
profile类型错误	profile 类型选择 “指定设备发布” 查看文档

如在操作过程中有任何疑问，欢迎随时联系蒲公英平台客服或技术支持团队。

Doc index

Problems encountered, contact us →