uni-app 鸿蒙 App 编译证书/签名错误排查全攻略

项目：Vue 3 + uni-app 3.0 App，编译目标 HarmonyOS App 环境：HBuilderX 5.x + DevEco Studio 5.0 + 鸿蒙真机 场景：点击「运行到鸿蒙」后，HBuilderX 报「权限没有签名授权」、或 hdc install 安装被拒

一、为什么这份文档有必要

HBuilderX 在「运行到鸿蒙」安装 .hap 失败时，控制台提示非常笼统，而且经常同一句提示对应完全不同的根因。例如下面这句：

22:18:57.314 运行所需的权限没有签名授权，请参考 配置文档
22:18:57.607 安装 .hap 到鸿蒙设备 ...
22:19:00.183 运行所需的权限没有签名授权，请参考 配置文档

光看这句话，你完全不知道到底是「设备没授权」「权限没授权」还是「证书坏了」。唯一可靠的排查手段，是绕过 HBuilderX，直接用 hdc install 把已签名的 hap 装一次，看鸿蒙系统返回的真实错误码。

二、排查利器：用 hdc install 拿真实错误

已签名的 hap 一般在：

dist/dev/app-harmony/entry/build/default/outputs/default/entry-default-signed.hap

用 DevEco 自带的 hdc 手动安装（路径按本机 DevEco 安装位置调整）：

$hdc = 'C:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe'
$hap = 'c:\jwdev-git\jwdev-app\dist\dev\app-harmony\entry\build\default\outputs\default\entry-default-signed.hap'

# 先看设备是否连上
& $hdc list targets

# 手动安装，看系统真实返回
& $hdc install $hap

这一步能直接告诉你鸿蒙拒绝安装的真实原因（错误码 + 权限名），比 HBuilderX 的笼统提示有用 100 倍。下面所有「类型」的底层报错都来自这里。

三、几类典型报错（完整文案记录）

类型 1：应用声明了未被调试证书授权的权限（最常见）

HBuilderX 控制台：

运行所需的权限没有签名授权，请参考 配置文档

hdc install 真实报错（实测）：

[Info]App install path:...entry-default-signed.hap
msg:error: failed to install bundle. code:9568289
error: install failed due to grant request permissions failed.
PermissionName: ohos.permission.READ_IMAGEVIDEO

注意最后一行 PermissionName: xxx —— 它精确告诉你是哪个权限没被授权。把这里的权限名记下来，对症下药。

根因： 应用在 module.json5 的 requestPermissions 里声明了某个权限（如 ohos.permission.READ_IMAGEVIDEO），但当前调试证书 profile（.p7b 文件）的授权列表里没有它，鸿蒙系统拒绝安装。

注意子类：

• 普通权限但 profile 未授权：如 READ_IMAGEVIDEO、VIBRATE。这些权限本身等级不高，只是当前调试 profile 没带上。
• ACL 受限权限（需白名单）：官方明确指出以下三项属于 ACL 受限权限，普通调试证书根本覆盖不了，必须有在 AGC 后台为该应用开通白名单的高权限证书：
  • ohos.permission.WRITE_IMAGEVIDEO
  • ohos.permission.WRITE_CONTACTS
  • ohos.permission.READ_PASTEBOARD

解法 A（最快，无需动证书）： 如果这个权限暂时用不到，直接从 harmony-configs/entry/src/main/module.json5 删除对应权限声明，重新「运行到鸿蒙」即可。

// harmony-configs/entry/src/main/module.json5
{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.VIBRATE" }
      // 删掉未被授权的那一条，例如 READ_IMAGEVIDEO
    ]
  }
}

解法 B（业务确实需要该权限）： 让调试证书 profile 也带上该权限授权。两个途径：

1. 在 HBuilderX 重新「配置调试证书」（用你自己的华为开发者账号申请），申请时 profile 会根据项目声明的权限自动加入授权；
2. 用 DevEco Studio 打开 dist/dev/app-harmony 工程，开启「自动签名」，DevEco 会用你的华为账号申请含对应权限授权的调试 profile；
3. 若是 ACL 受限权限，还需在 AGC/DCLOUD 后台给该应用开通媒体库等白名单，再重新生成证书。

声明权限的正确位置只有 harmony-configs/entry/src/main/module.json5，不是 manifest.json 的 app-harmony.distribute。详见《uni-app 鸿蒙 App 自定义配置全攻略》。

类型 2：调试设备（UDID）未授权

HBuilderX 控制台： 同样可能显示那句「运行所需的权限没有签名授权」或「设备未授权」。

hdc install 真实报错（典型）：

error: failed to install bundle. code:9568289
error: install failed due to grant request permissions failed.
PermissionName: xxx

或设备维度：

error: failed to install bundle. code:9568289
error: the device is not in the authorized device list of the provisioning profile

根因： 调试证书 profile（.p7b）里登记的 deviceIdList 不包含当前真机的 UDID。每台真机有唯一 UDID（用 hdc shell 'bm get --udid' 获取），调试证书只能装到登记过的设备上。

解法：

1. HBuilderX 菜单「运行 → 运行到手机或模拟器 → 运行到鸿蒙设备」时，首次会提示「配置调试证书」，按向导走，它会把当前连接设备加入 profile；
2. 或 DevEco Studio「自动签名」会自动把本机 UDID 写进 profile；
3. 若之前点过「配置调试证书」仍失败，确认 build-profile.json5 的 signingConfigs.material.profile 指向的 .p7b 确实包含本机 UDID（用 node 在 .p7b 二进制里搜本机 UDID 字符串即可验证）。

类型 3：签名配置损坏 / material 解密失败

HBuilderX 控制台（构建/签名阶段）：

运行所需的权限没有签名授权，请参考 配置文档

或构建期直接报解密失败：

error: failed to decrypt signing material
error: the signing material is invalid or corrupted

根因： harmony-configs/jwdev/signing/ 下的签名文件丢失、被覆盖，或 build-profile.json5 里 material 的 storePassword/keyPassword（密文）与 .p12 实际密码不匹配。常见诱因：手动改过签名目录、.gitignore 没管好签名文件、或在多套证书（如 agc.*、juanwangdev.*、jwdev2.*）之间来回切换导致引用错乱。

解法：

1. 用 keytool 验证 .p12 能否用 material 里的密码打开：
   text

   $kt = 'C:\Program Files\Huawei\DevEco Studio\jbr\bin\keytool.exe'
   & $kt -list -v -keystore harmony-configs\jwdev\signing\agc.p12 -storepass <material里的storePassword明文对应值>
   

2. 若文件损坏，重新「配置调试证书」让 HBuilderX 重新生成一整套（.p12 + .cer + .p7b），并确认 build-profile.json5 的 signingConfigs 引用的是同一套；
3. 把签名目录加入 .gitignore，避免被 git 误覆盖（见下方第五节）。

类型 4：证书与 profile 不匹配

hdc install 真实报错（典型）：

error: failed to install bundle. code:9568289
error: the certificate fingerprint does not match the provisioning profile

或签名阶段：

error: the signing certificate does not match the profile

根因： 用于签名的 .p12（及其 .cer）证书指纹，与 .p7b profile 里记录的「签发该 profile 的证书指纹」不一致。比如 build-profile.json5 里 storeFile 用了 A 证书，但 profile 指向的是 B 证书配套的 .p7b。多套证书并存时极易踩坑。

解法： 确保 build-profile.json5 的 signingConfigs.material 中 storeFile/certpath/profile 三者是同一套证书产物，不要跨套混用。

// harmony-configs/build-profile.json5（正确示范：三者同属 agc 套件）
{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "storeFile": "./jwdev/signing/agc.p12",
          "storePassword": "0000001B...",
          "keyAlias": "debugkey",
          "keyPassword": "0000001B...",
          "signAlg": "SHA256withECDSA",
          "profile": "./jwdev/signing/agc.p7b",
          "certpath": "./jwdev/signing/agc.cer"
        }
      }
    ]
  }
}

类型 5：点了「配置调试证书」反而更乱

这是本次排查中真实遇到的坑，单独列出来提醒。

现象： 运行前点了「配置调试证书」，HBuilderX 在 harmony-configs/jwdev/signing/ 下生成了新证书集（如 juanwangdev.*、jwdev2.*），但 build-profile.json5 仍引用旧的 agc.*。结果：新证书压根没被用上，旧证书 profile 又缺权限/缺设备，安装照样失败，排查时还会被一堆新旧证书文件搞晕。

根因： HBuilderX 生成的「配置调试证书」产物，需要 build-profile.json5 的 signingConfigs 实际引用它才会生效。如果之前手动锁定了 agc.*，新证书就是摆设；而且新证书的 .p12 密码由 HBuilderX 内部管理，手动写进 build-profile.json5 时往往拿不到密码。

解法：

• 最干净：删掉 build-profile.json5 里手写的 signingConfigs，让 HBuilderX 在「运行到鸿蒙」时自动套用「配置调试证书」生成的证书；
• 若必须手写，确保 storeFile/certpath/profile 指向同一套、且 .p12 密码正确（密码拿不到就别手写，交给 HBuilderX 自动管理）。

四、证书文件体系速查

harmony-configs/jwdev/signing/ 下常见几类文件，别混：

关键判断顺序：

1. hdc install 报哪个 PermissionName？→ 类型 1，去 module.json5 处理权限或换含授权的证书；
2. 报设备/UDID 不在列表？→ 类型 2，配置调试证书加入本机；
3. 报证书与 profile 指纹不匹配？→ 类型 4，确认三件套同属一套；
4. 报 material 解密失败 / 构建期就挂？→ 类型 3，恢复或重新生成签名文件；
5. 点了配置调试证书还乱？→ 类型 5，让 HBuilderX 自动管理签名，别手写错套。

五、防复发：把签名目录加入 .gitignore

签名文件（.p12/.cer/.p7b/material）不应进版本库，避免被别人/别分支的提交覆盖导致解密失败或证书错乱：

# .gitignore
harmony-configs/*/signing/
jwdev-app/harmony-configs/jwdev/signing/

六、核心教训

1. HBuilderX 的「运行所需的权限没有签名授权」是一句万能套话，同一句背后可能是权限、设备、证书、material 四种完全不同的问题。必须 hdc install 拿真实错误码才能定性。

2. code:9568289 + PermissionName: xxx 是定位金钥匙。它直接告诉你缺哪个权限授权，比任何猜测都准。

3. 权限声明只在 harmony-configs/entry/src/main/module.json5，不在 manifest.json。改了要重新「运行到鸿蒙」才会重新编译生效。

4. ACL 受限权限（WRITE_IMAGEVIDEO / WRITE_CONTACTS / READ_PASTEBOARD）普通调试证书覆盖不了，要么删声明，要么在后台开通白名单后重新申请证书。

5. 多套证书（agc / juanwangdev / jwdev2）极易混淆。build-profile.json5 的 storeFile/certpath/profile 必须同属一套，且 .p12 密码要对。点「配置调试证书」后若手写引用没跟上，新证书不会生效。

6. 签名文件别进 git，否则跨分支/跨人一覆盖就炸（类型 3）。

本文基于一次真实的「运行到鸿蒙安装被拒」排查整理，核心动作是用 hdc install 绕过 HBuilderX 笼统提示，拿到 code:9568289 ... grant request permissions failed. PermissionName: ohos.permission.READ_IMAGEVIDEO 这一真实报错，从而把「权限未授权 / 设备未授权 / 证书不匹配 / material 损坏 / 配置调试证书反乱」五类证书错误逐一区分清楚。