《uni-app开发Harmony Next平台的App》第二篇：项目运行与发行——将uni-app打包为鸿蒙安装包

1. 开篇：为什么要单独讲运行和发行？

很多开发者在用 uni-app 开发 HarmonyOS NEXT 应用时，前期的代码编写和本地调试还算顺利，但一到“运行到鸿蒙真机”或者“打包上架”环节就容易卡住。常见的问题包括：

运行环节： HBuilderX 识别不到鸿蒙设备、签名配置错误导致安装失败、模拟器启动后白屏。
发行环节： hap 包生成后无法安装、应用市场审核失败提示包名冲突或签名不一致。

这些问题的根源在于 HarmonyOS NEXT 的打包签名机制和 Android / iOS 完全不同——它使用 AppGallery Connect 签发的证书和 profile 文件，并且包名有严格的规则。如果只是照着官方文档匆匆过一遍，很容易忽略关键步骤。

这篇文章会从实际配置出发，把运行和发行的每一步拆开来讲。你不必担心看不懂，我会把每个配置项的作用类比到其他平台（比如“类似于 Android 的 keystore”、“和 iOS 的 provisioning profile 很像”），让你能快速理解背后的逻辑。

2. 环境说明

HBuilderX 版本：4.27 及以上（必须使用正式版，Beta 版可能有兼容问题）
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：HarmonyOS NEXT 真机（或远程模拟器）

如果你还没有注册华为开发者账号并开通 HarmonyOS 应用服务，请先完成这些基础准备（不在本文赘述）。

3. 运行到真机 / 模拟器

3.1 准备工作：连接鸿蒙设备

在 HBuilderX 中点击「运行」菜单，选择「运行到手机或模拟器」，下拉列表里如果看不到 HarmonyOS 设备，说明设备连接有问题。

• 真机： 打开开发者模式（设置 -> 关于手机 -> 连续点击版本号 7 次），进入开发者选项，开启「USB 调试」。然后用数据线连接电脑，手机上允许调试授权。
• 模拟器： 在华为 AppGallery Connect 中申请远程模拟器，会在本地生成一个 adb 类似的连接。HBuilderX 运行时会自动识别。

3.2 配置系统参数（必要的鸿蒙 SDK）

在 HBuilderX 顶部菜单栏选择「设置」->「运行配置」，找到「HarmonyOS 运行配置」：

• DevEco Studio 目录：配置你本机 DevEco Studio 的安装路径（HBuilderX 会调用其中的工具链）
• HarmonyOS SDK 目录：一般由 DevEco Studio 自动管理，如果手动指定，需确保 SDK 版本 >= 6.1.0

3.3 第一次运行：自动生成签名证书

当你点击「运行」后，HBuilderX 会检查项目里是否已经配置了 HarmonyOS 签名。如果没配置，会弹出一个引导对话框，让你注册/登录华为开发者账号，并自动申请一个 调试证书 和 调试 profile。

这个过程是自动化的，但有一个关键点：调试证书的有效期通常只有30天。如果你的项目隔了一段时间再运行，发现报错“证书已过期”，就需要重新生成一次。最简单的方法是在 HBuilderX 的「运行」菜单里选择「重新生成 HarmonyOS 调试证书」。

类比：这类似于 iOS 开发中 Xcode 自动管理开发证书和描述文件。

3.4 运行后的现象

运行成功后，HBuilderX 的控制台会输出：

[Harmony] 打包成功：/path/to/app/build/outputs/default/entry-default-signed.hap
[Harmony] 正在安装到设备...
[Harmony] 安装成功，启动中...

手机上会出现你应用的图标，点击即可启动。如果遇到安装失败，请检查：

• 设备是否开启了「仅安装来自华为应用市场的应用」？需要关闭该选项（在开发模式下会自动关闭）。
• 包名是否与应用市场某已上架应用冲突？（调试阶段不影响，正式发行时需要注意）

4. 发行流程：生成 hap 安装包

4.1 配置 manifest.json 的发行参数

发行前，必须正确填写 manifest.json 中的鸿蒙相关配置。用源码方式打开该文件，找到 "app-plus" -> "distribute" -> "harmony" 节点。如果没有，手动添加：

{
  "app-plus": {
    "distribute": {
      "harmony": {
        "appIdentifier": "com.example.myapp",   // 包名，全网唯一，建议倒置域名
        "versionCode": 1,                        // 内部版本号（自增整数）
        "versionName": "1.0.0",                  // 对外版本号
        "minSdkVersion": 60100023,               // 最低支持鸿蒙系统版本（6.1.0.23）
        "icon": "static/logo.png",               // 应用图标路径
        "label": "我的应用"                      // 应用名称
      }
    }
  }
}

重点：

• appIdentifier 一旦确定，后续版本不能修改。它对应华为 AppGallery Connect 上应用的包名。
• versionCode 每次上架新包必须递增，否则会被驳回。
• minSdkVersion 建议不低于 60100023，覆盖大部分 HarmonyOS NEXT 设备。

4.2 申请正式的签名证书和 profile

调试证书只用于本地运行，正式发行必须申请发布证书。

1. 登录 AppGallery Connect，进入「我的项目」->「添加应用」（如果还没有应用）。
2. 在「开发」->「HarmonyOS 应用」->「证书管理」中，点击「新建证书」。
   • 证书类型：选择“发布证书”
   • 生成 CSR 文件时会让你下载一个工具（DevEco Studio 自带生成 CSR 功能，或使用 HBuilderX 里的“华为证书管理”工具）
3. 拿到证书（.cer 文件）后，在「Profile 管理」中创建发布 profile，绑定该证书和应用包名。
4. 下载 profile 文件（.p7b）和证书文件（.cer），保存在项目目录的 nativecfg/harmony/ 下（如果不存在则创建）。

HBuilderX 会在发行时自动读取这个目录下的证书文件。你也可以通过菜单「发行」->「鸿蒙应用打包」->「选择证书文件」手动指定。

类比：发布证书相当于 Android 的 release key store，profile 相当于 iOS 的 App Store provisioning profile。

4.3 执行发行打包

1. 在 HBuilderX 顶部菜单选择「发行」->「鸿蒙应用打包」->「打包为 hap 包」。
2. 在弹出的对话框中：
   • 勾选“使用发布证书”（如果已经配置了发布证书文件）
   • 签名算法选择 SHA256withRSA（默认）
   • 点击「打包」。
3. 等待几分钟，打包完成后会在 unpackage/release/harmony/ 目录下生成 app-release-signed.hap文件。

该文件就是可以直接安装到 HarmonyOS NEXT 设备上的安装包。在未上架前，你可以用 adb 命令手动安装进行最终验证：

hdc install -r path/to/app-release-signed.hap

4.4 上传到华为应用市场

1. 登录 AppGallery Connect，进入应用管理，选择你的应用，点击「版本管理」->「创建版本」。
2. 选择“HarmonyOS 应用”类型，上传 .hap 文件。
3. 填写应用描述、截屏、隐私协议等。注意：
   • 隐私协议：必须填写，且与应用内 plus.runtime.openURL 等权限匹配。
   • 目标设备：如果你的应用只在手机运行，别勾选平板或折叠屏，否则可能因为 UI 适配问题被驳回。
4. 提交审核。审核周期通常 1-3 个工作日，周末可能延迟。

5. 常见问题（踩坑记录）

问题 1：真机调试时提示“证书不受信任”，无法安装

现象： 手机显示“未通过签名校验”或“安装失败：INVALID_INSTALL_PARAM”。

原因： 设备上的开发者模式证书与 HBuilderX 生成的调试证书不匹配。常见于切换了电脑或换了设备后重新运行。

解法： 在 HBuilderX 运行菜单里选择「清除调试证书」，再重新运行一次，让 HBuilderX 重新生成证书并安装到设备上。手机端也需要清理旧的调试信任（设置->系统和更新->认证管理->删除旧的 HBuilder 证书）。

问题 2：发行打包时提示“未找到发布证书或 profile”

现象： 控制台报错“Cannot find matching certificate for release signing”。

原因： HBuilderX 在 nativecfg/harmony/ 下没有找到 .cer 和 .p7b 文件，或者文件命名不规范。

解法： 检查项目根目录是否有 nativecfg/harmony/ 文件夹，并在其中放入以下文件：

• release.cer（发布证书）
• release.p7b（发布 profile）
  文件名必须严格匹配，否则不会被读取。你也可以在发行对话框里手动指定文件路径。

问题 3：应用上架后提示“签名不一致”被拒绝

现象： 上传 hap 包后，应用市场返回“包签名与服务端记录不一致”。

原因： 你使用了不同于该应用在 AppGallery Connect 上绑定的证书。可能是在调试阶段用了不同的包名申请了调试证书，而上架时换了包名或新的发布证书。

解法： 确保 appIdentifier 与你最初在 AppGallery Connect 创建应用时填写的包名完全一致。然后在「证书管理」里确认当前发布证书的指纹与应用市场后台记录一致。不一致时需要重新下载对应证书文件。

6. 最佳实践

• 版本号管理： 在 manifest.json 里维护 versionCode 和 versionName。建议 versionCode 使用日期加序号（如 2025041201），避免递增混乱。
• 证书文件纳入版本控制？ 不建议把发布证书和 profile 提交到 git 仓库，因为它们包含私钥。可以在本地备份专用目录。调试证书可以提交，因为每次重新运行都会重新生成。
• 打包前做一次全量回归： 发行包与调试运行包的环境略有不同（有些 API 在 release 模式下行为不同），建议打包后在真机上做一次完整的功能测试，尤其是涉及支付的场景。

7. FAQ

Q：为什么我的 HBuilderX 运行菜单里找不到鸿蒙设备选项？
A：确保 HBuilderX 版本 >= 4.27，并且你的项目是 vue3 编译模式。旧项目如果是 vue2，需要先升级到 vue3。另外检查 manifest.json 中是否配置了 "harmony" 分发节点（如果只写了 "app-plus" 但没有 harmony 子项，HBuilderX 不会启用鸿蒙支持）。

Q：我可以直接使用 Android 的包名（com.example.app）作为鸿蒙包名吗？
A：可以，鸿蒙包名规则与 Android 类似，使用倒置域名。但注意：同一个应用在华为应用市场上，Android 版本和鸿蒙版本是分开管理的，包名可以相同，但签名证书完全不同。

Q：调试时能否使用发布证书？
A：不建议。发布证书申请后不能用于调试（设备会认为证书未授权调试）。调试证书和发布证书是两套体系，互不通用。在 HBuilderX 中，运行模式始终使用自动生成的调试证书，发行模式才允许指定发布证书。

Q：hap 包的上传大小有限制吗？
A：华为应用市场对 hap 包的大小限制为 4GB（实际上是 4GB 以内），但建议控制在 200MB 以内，否则用户下载体验差。如果包过大，可以启用 App Bundle 拆分资源包。

---

示例代码地址（注意： 这是通用示例，你需要替换自己的包名）
本文中涉及的 manifest.json 配置片段可以直接复制到你的项目中，但请确保 appIdentifier 唯一。
官方文档参考：https://uniapp.dcloud.net.cn/tutorial/harmony/runbuild.html