如何将鸿蒙安装包发给别人安装

一、前言

在鸿蒙应用开发过程中，将安装包分发给测试人员或其他开发者进行验证，是开发流程中不可或缺的一环。然而，鸿蒙应用的分发并不像传统Android应用那样可以直接发送APK文件安装，而是需要根据项目结构选择合适的打包方式，并确保签名配置正确。

本文将从环境准备入手，系统介绍在两种不同项目场景下（无HSP / 有HSP）的打包与分发方案。特别值得一提的是，从API version 22开始，hdc install命令原生支持安装.app应用包，这极大地简化了包含HSP的复杂项目的安装流程。同时，我会重点分享自己在实际开发中遇到的9568320签名错误及其完整的排查解决过程，希望帮助大家少走弯路。

二、环境准备

在进行应用打包和分发之前，需要准备好hdc（HarmonyOS Device Connector）调试工具。hdc是鸿蒙为开发人员提供的用于调试的命令行工具，通过该工具可以在Windows/Linux/Mac系统上与真实设备或者模拟器进行交互。

2.1 获取hdc工具

hdc可以通过以下两种方式获取：

方式一：通过HarmonyOS SDK获取

HarmonyOS SDK已嵌入DevEco Studio中，无需额外下载配置。hdc默认安装在以下路径：

• Windows：DevEco Studio/sdk/default/openharmony/toolchains
• MacOS：DevEco Studio/Contents目录下

方式二：通过Command Line Tools获取

hdc程序默认安装在Command Line Tools/sdk/default/openharmony/toolchains路径下。

2.2 配置环境变量（可选）

为了方便在任意目录下执行hdc命令，可以将hdc所在目录添加到系统环境变量中。

Windows系统：在“设置”中搜索“查看高级系统设置”，进入“环境变量 > 系统变量 > Path > 编辑”，将hdc.exe所在目录添加到Path中，配置完成后重启电脑。

Linux/MacOS系统：打开终端，执行echo $SHELL判断使用的Shell类型。如果输出为bin/bash，编辑~/.bashrc文件；如果输出为/bin/zsh，编辑~/.zshrc文件。在文件末尾添加：

export PATH={DevEco Studio}/sdk/default/openharmony/toolchains:$PATH

其中{DevEco Studio}需替换为实际安装目录的绝对路径。编辑完成后执行source ~/.bashrc或source ~/.zshrc使配置生效。

2.3 开启设备调试

在设备的“设置 > 系统 > 开发者选项”中开启调试开关，无需重启设备即可生效。如果设备未启用“开发者选项”，可参考官方文档进行启用。

三、项目中没有HSP的情况下直接安装HAP即可

HAP是鸿蒙应用的基本安装包格式。当你的项目不包含HSP（HarmonyOS Shared Package，动态共享包）时，可以直接将HAP包发给他人安装。

3.1 生成HAP包

在DevEco Studio中，选择菜单栏“Build > Build HAP(s)/APP(s) > Build HAP(s)”进行编译。生成的.hap文件位于工程目录下的build > outputs > default文件夹中。

3.2 分发HAP包

将生成的HAP包通过微信、邮件等方式发送给测试人员。前提条件：HAP包必须已完成签名。在已经签名的情况下，把带有signed前缀的hap包发给别人，别人也可以安装。

3.3 安装HAP包

测试人员收到HAP包后，可以通过以下方式安装：

方式一：使用hdc命令安装

在命令行中执行：

hdc install /path/to/your_app.hap

hdc install是直接安装hap包到设备的命令，适用于本地文件安装。如果包含的HAP和HSP包不多，可以使用命令依次安装，但需要注意先安装HSP包再安装HAP包。

方式二：使用DevEco Testing工具

连接真机后，选择实用工具，点击开始投屏，点击右侧“安装应用”即可选择HAP包进行安装，不过只支持hap和zip格式。

方式三：模拟器拖拽安装

如果使用的是模拟器，直接将HAP包拖动到模拟器屏幕上即可完成安装。

3.4 注意事项

• 本地debug HAP更适合通过DevEco或hdc安装，不适合制作公开链接让任意设备直接安装，因为签名、设备授权和安装来源都会受到限制。
• 调试包仅限开发阶段使用。
• 发布证书签名的应用不支持通过hdc安装到手机上。

四、项目中有HSP的情况下需打包成APP进行安装

当项目中包含HSP时，情况会变得复杂一些。HSP实现了多个HAP对文件的共享，如果只单独安装HAP而不包含HSP，应用将无法正常运行。

4.1 为什么需要打包成APP

• 如果包含的HAP和HSP包不多，可以使用命令依次安装，但需要注意先安装HSP包再安装HAP包。
• 如果包较多，使用逐个安装的方式不仅繁琐，还容易出错。更规范的做法是将所有HAP和HSP打包成一个APP文件统一分发。

4.2 生成APP包

在DevEco Studio中，选择菜单栏“Build > Build HAP(s)/APP(s) > Build APP(s)”进行编译。生成的.app文件位于工程目录下的build > outputs > default文件夹中。

4.3 分发APP包

将生成的.app文件发送给测试人员。测试人员可以通过以下方式安装：

方式一：通过AppGallery Connect分发（推荐）

登录AppGallery Connect网站，在“我的项目”中创建应用，进入“质量分析 > 测试”模块。将生成的.app包上传为“测试版本”，添加测试人员（通过华为账号）并生成公开的下载链接或二维码供其安装。

方式二：通过hdc命令直接安装（从API version 22开始支持）

这是本文特别要强调的便捷方式。从API version 22起，hdc install命令已原生支持安装.app应用包，不再需要像以前那样先解压再分别安装HAP和HSP。您只需在命令行执行：

hdc install /path/to/your_app.app

即可一键完成整个应用的安装，系统会自动解析APP包内的所有HAP和HSP并正确部署。这一特性大大简化了包含多个共享包项目的测试分发流程，也是我在实际工作中非常推荐的方式。

五、安装APP时9568320报错解决（亲身踩坑分享）

5.1 错误现象

在安装应用时，可能会遇到以下错误信息：

Install Failed: error: failed to install bundle. code:9568320 error: no signature file.

这个错误是我在实际开发中遇到的。当时我打包了一个APP发给同事测试，对方一安装就报这个错，排查了很长时间才发现是签名遗漏问题。现在我把完整的解决过程整理出来，希望能帮助大家快速定位。

5.2 错误原因

该错误码表示签名文件不存在，即用户安装的是未签名的HAP/HSP包。可能的原因包括：

1. 工程级build-profile.json5文件中未配置signingConfigs签名配置，或products中未指定对应的signingConfig
2. DevEco Studio缓存异常导致签名失效
3. 证书类型使用不正确（调试包使用了发布证书，或反之）

5.3 解决方案

请开发者根据实际场景选择自动签名或者手动签名。

方法一：使用自动签名（最快捷）

在连接设备后，重新为应用进行签名。具体操作：

1. 进入File > Project Structure... > Project > Signing Configs界面
2. 勾选“Automatically generate signature”
3. 完成签名配置

方法二：使用手动签名

如果使用多台调试设备或需要在断网情况下调试，需要在AGC中申请调试证书、注册调试设备、申请调试Profile后，再手动配置签名信息。

在build-profile.json5中配置签名信息：

"signingConfigs": [{
    "name": "default",
    "material": {
        "storeFile": "xxx.p12",
        "storePassword": "xxx",
        "keyAlias": "xxx",
        "keyPassword": "xxx",
        "profile": "xxx.p7b",
        "certpath": "xxx.cer",
        "signAlg": "SHA256withECDSA"
    }
}]

并在products中指定对应的signingConfig：

"products": [{
    "name": "default",
    "signingConfig": "default",
    ...
}]

方法三：配置appWithSignedPkg属性（针对APP包，我遇到的就是这个情况）

如果安装APP时报这个错误码，需要在工程级build-profile.json5文件里配置packOptions的appWithSignedPkg属性为true，保证APP里的HAP/HSP有签名：

"packOptions": {
    "appWithSignedPkg": true
}

这个配置是我在反复尝试后发现的官方解决方案，针对APP包打包时内部模块签名遗漏的情况。

六、总结

将鸿蒙安装包分发给他人安装测试，核心流程可以归纳为以下几个关键点：

1. 根据项目结构选择打包方式

• 项目中没有HSP：直接打包HAP，通过hdc install .hap安装即可
• 项目中有HSP：打包成APP，优先使用hdc install .app（API 22+）一键安装，这是目前最推荐的统一分发方式

2. 签名是必须的前置条件
无论采用哪种方式分发，都必须先为应用配置有效的签名证书。自动签名适用于单台调试设备的快速开发场景，手动签名适用于多设备或断网场景。

3. 分发渠道的选择

• 少量设备快速测试：HAP/APP直装 + hdc命令
• 多测试人员协作：AppGallery Connect测试版本分发

4. 常见问题处理（来自实战经验）
遇到9568320签名错误时，优先检查build-profile.json5中的签名配置和products引用，其次尝试清理缓存并删除本地签名目录重新生成，最后确认证书类型是否正确。对于APP包，别忘了配置appWithSignedPkg: true。

小技巧：DevEco Testing 装应用时默认只认 .hap 和 .zip，不认 .app。遇到这种情况，直接把后缀改成 .zip 就能装上了，亲测有效。

掌握以上方法后，无论项目是否包含HSP，你都能高效地将鸿蒙应用打包分发给测试人员，顺利完成应用的验证与迭代工作。希望我的这些实战踩坑经验能为你节省宝贵的时间！