如何将鸿蒙安装包发给别人安装一、前言在鸿蒙应用开发过程中将安装包分发给测试人员或其他开发者进行验证是开发流程中不可或缺的一环。然而鸿蒙应用的分发并不像传统Android应用那样可以直接发送APK文件安装而是需要根据项目结构选择合适的打包方式并确保签名配置正确。本文将从环境准备入手系统介绍在两种不同项目场景下无HSP / 有HSP的打包与分发方案。特别值得一提的是从API version 22开始hdc install命令原生支持安装.app应用包这极大地简化了包含HSP的复杂项目的安装流程。同时我会重点分享自己在实际开发中遇到的9568320签名错误及其完整的排查解决过程希望帮助大家少走弯路。二、环境准备在进行应用打包和分发之前需要准备好hdcHarmonyOS Device Connector调试工具。hdc是鸿蒙为开发人员提供的用于调试的命令行工具通过该工具可以在Windows/Linux/Mac系统上与真实设备或者模拟器进行交互。2.1 获取hdc工具hdc可以通过以下两种方式获取方式一通过HarmonyOS SDK获取HarmonyOS SDK已嵌入DevEco Studio中无需额外下载配置。hdc默认安装在以下路径WindowsDevEco Studio/sdk/default/openharmony/toolchainsMacOSDevEco 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是鸿蒙应用的基本安装包格式。当你的项目不包含HSPHarmonyOS 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.haphdc 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包。可能的原因包括工程级build-profile.json5文件中未配置signingConfigs签名配置或products中未指定对应的signingConfigDevEco Studio缓存异常导致签名失效证书类型使用不正确调试包使用了发布证书或反之5.3 解决方案请开发者根据实际场景选择自动签名或者手动签名。方法一使用自动签名最快捷在连接设备后重新为应用进行签名。具体操作进入File Project Structure... Project Signing Configs界面勾选“Automatically generate signature”完成签名配置方法二使用手动签名如果使用多台调试设备或需要在断网情况下调试需要在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中指定对应的signingConfigproducts: [{ 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 .appAPI 22一键安装这是目前最推荐的统一分发方式2. 签名是必须的前置条件无论采用哪种方式分发都必须先为应用配置有效的签名证书。自动签名适用于单台调试设备的快速开发场景手动签名适用于多设备或断网场景。3. 分发渠道的选择少量设备快速测试HAP/APP直装 hdc命令多测试人员协作AppGallery Connect测试版本分发4. 常见问题处理来自实战经验遇到9568320签名错误时优先检查build-profile.json5中的签名配置和products引用其次尝试清理缓存并删除本地签名目录重新生成最后确认证书类型是否正确。对于APP包别忘了配置appWithSignedPkg: true。小技巧DevEco Testing 装应用时默认只认 .hap 和 .zip不认 .app。遇到这种情况直接把后缀改成 .zip 就能装上了亲测有效。掌握以上方法后无论项目是否包含HSP你都能高效地将鸿蒙应用打包分发给测试人员顺利完成应用的验证与迭代工作。希望我的这些实战踩坑经验能为你节省宝贵的时间