HarmonyOS开发——解决 HarmonyOS 真机调试报错 9568320：no signature file 完整排查指南

错误码 9568320，提示 no signature file，自动签名、关联已注册应用都试了还是不行？本文记录了一次完整的排查过程，最终根因出人意料地简单。

---

一、问题现象

在 DevEco Studio 中将 HarmonyOS 应用运行到真机时，安装阶段报错：

code: 9568320
error: no signature file.

该错误码的含义是：安装的 HAP/HSP 包中没有签名文件，即构建产物实际上未被签名。

尝试过的无效方案

• ✅ 开启自动生成签名文件 → 仍然报错
• ✅ 关联已注册应用 → 仍然报错
• ✅ 保存后重新运行到真机 → 仍然报错

两个方案都"看起来操作成功了"，但真机安装时始终报 9568320。

---

二、排查过程

第一步：确认构建产物是否真的未签名

打开工程的构建输出目录 build/default/outputs/default/，查看生成的 HAP 文件名。

关键发现：文件名包含 unsigned，如 entry-default-unsigned.hap。

这说明 签名配置虽然开启了，但构建阶段完全没有将签名写入产物。问题不在安装环节，而在构建环节。

第二步：检查 build-profile.json5 配置绑定

打开工程级 build-profile.json5，重点检查 products 中的 signingConfig 字段：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",       // 签名配置名称
        "type": "HarmonyOS",
        "material": { ... }
      }
    ],
    "products": [
      {
        "name": "default",
        // ❌ signingConfig 字段缺失！
        "compatibleSdkVersion": "5.0.0(12)"
      }
    ]
  }
}

根因定位：products 中缺少 signingConfig 字段！

虽然 signingConfigs 中已经定义了签名配置，material 中也有完整的证书材料，但由于 products 没有通过 signingConfig 字段引用该配置，构建时 直接跳过了签名步骤，生成了 unsigned 包。

第三步：修复配置

在 products 中补充 signingConfig 字段，使其值与 signingConfigs 的 name 完全一致：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": { ... }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",  // ✅ 补充此字段，值与上方 name 一致
        "compatibleSdkVersion": "5.0.0(12)"
      }
    ]
  }
}

保存后重新构建，产物文件名不再包含 unsigned，真机安装成功，问题解决。

---

三、根因分析

flowchart TD A[开启自动签名] --> B[signingConfigs 中生成签名配置] B --> C[products 中需要通过 signingConfig 字段引用] C --> D{signingConfig 字段是否存在} D -->|存在且值匹配| E[构建时写入签名] E --> F[生成 signed.hap] F --> G[真机安装成功] D -->|缺失或值不匹配| H[构建时跳过签名] H --> I[生成 unsigned.hap] I --> J[真机安装报错 9568320]

核心原因在于：自动签名只负责生成签名配置（signingConfigs），但不会自动将配置绑定到 products。如果 products 中缺少 signingConfig 字段，构建流程无从得知该使用哪个签名配置，于是直接输出未签名的包。

这个问题的隐蔽性在于：

• DevEco Studio 的自动签名 UI 操作不会报错
• signingConfigs 中看起来配置完整
• 只有深入检查 build-profile.json5 的绑定关系才能发现

---

四、完整排查清单

如果补充 signingConfig 字段后仍未解决，可按以下清单继续排查：

1. 确认当前运行选择的 product

多 product 工程中，可能出现只给 default 配了签名，但实际运行时切换到了另一个 product 的情况。请在 DevEco Studio 顶部工具栏确认当前选择的 product。

2. 多模块项目检查 target 级别配置

打开模块级 build-profile.json5，确认 target 是否关联了正确的 signingConfig。

3. 彻底清理缓存重新签名

配置正确但仍然生成 unsigned，可能是 DevEco Studio 缓存异常：

flowchart TD A[关闭自动签名并Apply] --> B[关闭DevEco Studio] B --> C[删除工程下 .hvigor 目录] C --> D[删除工程下 build 目录] D --> E[删除本地签名配置目录] E --> F[重新打开DevEco Studio] F --> G[重新开启自动签名] G --> H[Clean Project] H --> I[Rebuild Project] I --> J[检查产物是否已签名]

本地签名配置目录路径：

• Windows：C:\Users\你的用户名\.ohos\config
• Mac/Linux：~/.ohos/config

4. 检查签名生成是否静默失败

重新开启自动签名后，检查 build-profile.json5 中 signingConfigs 的 material 字段是否被自动填充了实际文件路径。如果为空，说明签名生成静默失败，需排查以下原因：

排查项	具体说明
开发者账号未实名认证	自动签名需与 AppGallery Connect 交互，未实名会导致静默失败
自动签名次数超限	同一开发者账号 30 天内不超过 150 次
AGC 调试证书数量达上限	需在 AppGallery Connect 平台删除旧证书
网络或代理问题	HTTP 代理设置为自动检测
本地 PC 时间不一致	需与北京时间一致
JDK 环境缺失	本地需正确配置 JDK
IDE 未识别调试设备 UDID	设备未正确连接时签名流程可能被跳过

5. 安装 APP 包时的特殊配置

如果报错发生在安装 APP 包（非单个 HAP）时，需在工程级 build-profile.json5 中配置：

{
  "app": {
    "packOptions": {
      "appWithSignedPkg": true
    }
  }
}

6. 应急替代方案：手动签名

如果自动签名反复尝试均无法生效，可切换为手动签名，绕过网络交互环节：

1. 登录 AppGallery Connect 平台，创建调试证书（.cer）和调试 Profile（.p7b）
2. 本地生成密钥库文件（.p12）
3. 在 build-profile.json5 中手动配置 material 字段，指向本地证书文件
4. 确认 products 中 signingConfig 字段已正确绑定
5. Clean Project → Rebuild Project

---

五、总结

项目	内容
错误码	9568320
错误信息	no signature file
直接原因	构建产物为 unsigned 包，未包含签名文件
根因	build-profile.json5 中 products 缺少 signingConfig 字段，导致构建时跳过签名
解决方案	在 products 中补充 signingConfig 字段，值与 signingConfigs 的 name 一致
排查关键	先检查产物文件名是否含 unsigned，再检查配置绑定关系

经验教训

1. 自动签名 ≠ 自动绑定：DevEco Studio 的自动签名功能只负责生成签名配置，products 中的 signingConfig 绑定字段需要手动确认或由 IDE 正确写入
2. 先查产物再查配置：遇到签名相关报错，第一步应检查构建产物文件名是否包含 unsigned，可以快速定位问题出在构建阶段还是安装阶段
3. build-profile.json5 是核心：签名相关的所有配置都在这个文件中，遇到签名问题优先检查此文件的 signingConfigs 与 products 的绑定关系

---

一句话总结：报错 9568320 别急着清缓存换证书，先看看 build-profile.json5 里 products 的 signingConfig 字段在不在。
内容由 AI 生成，仅供参考