HarmonyOS 证书从 0 到发布：DevEco Studio 签名与 Profile 实战

HarmonyOS 签名问题通常不是某一个文件损坏，而是应用身份、密钥、证书、Profile、权限和构建配置没有对齐。本文按可重复验证的工程流程整理。DevEco Studio、HarmonyOS SDK 与 AppGallery Connect 会持续更新，具体菜单名称和发布规则应以当前版本为准。

先分清 HarmonyOS 签名材料

手动配置 HarmonyOS 签名时，经常会看到下面几类文件和字段：

• 密钥库：常见为 .p12，保存用于签名的私钥。
• Key Alias：密钥库中具体密钥条目的名称。
• 签名证书：与私钥对应的证书，用于确认签名身份。
• Profile：常见为 .p7b，绑定应用身份、证书、设备范围和允许的能力。
• bundleName：HarmonyOS 应用的稳定身份，必须与工程和后台配置一致。
• appIdentifier：由平台和应用身份共同确定，最终会进入签名与 Profile 校验链路。

仅有 Profile 不能签名，仅有 .p12 也不能完成发布配置。真正可用的 Release 签名，需要私钥、证书、Profile 和应用身份同时匹配。

自动签名还是手动签名

自动签名

适合本地开发、个人调试和快速真机验证。DevEco Studio 登录开发者账号后，可以为当前项目申请或同步调试所需的签名材料，减少手动创建证书和设备 Profile 的步骤。

自动签名方便，但不要把它直接等同于团队发布方案。需要多人协作、固定 Release 身份、CI 构建或权限审计时，仍应明确签名资产存放位置和使用范围。

手动签名

适合正式发布、CI、多个环境并行和严格管理签名材料的项目。手动签名可以清晰控制：

• 哪个产品使用哪个 bundleName。
• 哪个环境使用哪个 Profile。
• 哪个证书负责正式发布。
• 哪条 CI 流水线可以读取私钥。

生产签名不要与个人开发环境混用，也不要依赖某一台开发机长期保存唯一私钥。

第一步：确认应用身份

正式创建证书和 Profile 前，先固定工程中的应用身份。示例：

{
  "app": {
    "bundleName": "com.example.product",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0"
  }
}

实际字段位置取决于项目结构和 SDK 版本，但检查原则不变：

1. bundleName 与 AppGallery Connect 中登记的应用一致。
2. 测试、预发布和生产环境有明确的身份策略。
3. 不要在应用已经上线后随意更换正式 bundleName。
4. Module、Extension 和主应用之间的身份关系符合工程设计。

如果 bundleName 不一致，后续即使证书和密码都正确，Profile 校验仍会失败。

第二步：准备密钥库与 CSR

在 DevEco Studio 或配套证书工具中创建密钥库时，需要设置：

• Keystore 文件路径。
• Store Password。
• Key Alias。
• Key Password。
• 证书主体和有效期。
• 签名算法。

正式项目应使用团队统一规则命名，例如：

product-release.p12
product-release

不要在文件名中包含密码、个人姓名或无法追踪的临时代号。

生成密钥和 CSR 后，应立即记录密钥库文件哈希、Alias、创建日期、负责人和备份位置。CSR 可以提交给平台申请证书，但用于签名的私钥仍保存在 .p12 中。

第三步：申请发布证书

在 AppGallery Connect 或当前证书管理入口上传 CSR，申请用于 HarmonyOS 应用发布的证书。下载后检查证书的用途、有效期和关联账号。

发布证书不是应用源码的一部分，不能提交到公开仓库。建议建立签名资产登记表：

字段	示例内容
用途	HarmonyOS Release
密钥库	product-release.p12
Alias	product-release
证书到期日	受控记录
Profile	正式发布 Profile
使用方	发布 CI
备份位置	团队密钥库

登记表只记录标识和位置，不直接填写密码。

第四步：创建发布 Profile

Profile 会把应用身份、证书和允许的能力组合起来。创建前确认：

1. 选择了正确的 HarmonyOS 应用。
2. bundleName 与工程一致。
3. 选择的是当前发布证书。
4. Profile 类型符合调试或发布场景。
5. 需要的权限与服务已经在后台启用。

下载得到的 .p7b 文件应与证书和 .p12 成组管理。证书更新、能力变化或应用身份调整后，旧 Profile 可能不再适用，需要重新生成。

不要只根据 Profile 文件名判断内容。团队应记录它对应的应用、证书、环境和到期时间。

第五步：配置 DevEco Studio 手动签名

在项目签名配置中填写 Release 所需材料。不同版本的配置文件结构可能有差异，核心字段通常包括：

{
  "signingConfigs": [
    {
      "name": "release",
      "type": "HarmonyOS",
      "material": {
        "certpath": "./signing/release.cer",
        "storePassword": "${SIGN_STORE_PASSWORD}",
        "keyAlias": "product-release",
        "keyPassword": "${SIGN_KEY_PASSWORD}",
        "profile": "./signing/release-profile.p7b",
        "signAlg": "SHA256withECDSA",
        "storeFile": "./signing/product-release.p12"
      }
    }
  ]
}

上面只用于说明字段关系，不应把真实密码直接写入项目配置。项目实际支持的变量注入方式，应以当前 Hvigor、DevEco Studio 和 CI 环境为准。

配置后检查 Release product 是否明确引用 release 签名，而不是继续使用默认调试签名。

第六步：构建 Release HAP

可以从 DevEco Studio 选择 Release 构建，也可以使用项目中的 Hvigor Wrapper。常见形式如下：

./hvigorw clean
./hvigorw assembleHap --mode module -p product=default -p buildMode=release

不同项目的 product、module 和任务名称可能不同，应先查看当前工程可用任务。构建完成后记录：

• HAP 输出路径。
• bundleName。
• versionCode 与 versionName。
• product 与 buildMode。
• 使用的签名配置名称。
• 构建时间和源码版本。

不要只保留“构建成功”的日志。发布产物需要能追溯到具体提交、配置和签名身份。

发布前检查 HAP

发布前至少完成以下检查：

1. 使用 DevEco Studio 或当前 SDK 提供的签名验证工具检查 HAP。
2. 解包检查 module.json 或当前模块描述中的身份、版本和权限。
3. 确认最终产物不是 debug 包。
4. 确认签名 Profile 与发布环境一致。
5. 在目标设备完成安装、启动、登录、推送和关键能力验证。

如果 SDK 提供 hap-sign-tool，应使用当前 SDK 内置版本执行 verify 操作，避免复制网络上与当前 SDK 不匹配的旧版 JAR 和命令参数。

权限与 Profile 为什么经常不匹配

HarmonyOS 权限和系统能力可能同时受到工程声明、平台申请和 Profile 的约束。常见问题包括：

• 工程新增权限，但正式 Profile 没有刷新。
• 调试 Profile 可以运行，发布 Profile 缺少对应能力。
• 使用了另一个应用或另一个 bundleName 的 Profile。
• Extension 使用的身份或能力未正确纳入签名配置。

排查时不要只看 IDE 报错最后一行。应按以下顺序核对：

1. 工程声明了什么权限和能力。
2. AppGallery Connect 为应用开启了什么能力。
3. Profile 实际包含什么应用身份和授权。
4. 最终 HAP 的签名与模块描述是什么。

CI 中如何管理签名材料

CI 不应长期把 .p12、证书和 Profile 放在工作目录。推荐流程：

1. 从受控凭据系统下载或解密签名材料。
2. 写入任务临时目录。
3. 通过环境变量提供密码。
4. 构建前检查文件存在、权限和哈希。
5. 构建后执行签名验证。
6. 上传 HAP 和校验信息。
7. 无论任务成功失败，都删除临时材料。

示例检查脚本：

set -euo pipefail

test -f "$HARMONY_KEYSTORE_PATH"
test -f "$HARMONY_CERT_PATH"
test -f "$HARMONY_PROFILE_PATH"

./hvigorw assembleHap \
  --mode module \
  -p product=default \
  -p buildMode=release

不要在日志中输出密码、Base64 密钥内容或完整的签名配置文件。CI 平台中应限制哪些任务、分支和人员可以读取生产签名凭据。

签名材料怎么备份

正式发布前至少准备两份加密备份，并确认可以恢复：

• .p12 密钥库。
• Store Password 与 Key Password。
• Key Alias。
• 发布证书。
• 发布 Profile。
• 证书与 Profile 到期时间。
• 应用 bundleName 和使用环境。

备份文件和密码应分开保存。每次轮换后执行一次隔离环境恢复演练，确认新环境能够完成 Release 构建和签名验证。

常见错误怎么排查

密钥库密码或 Alias 错误

先确认拿到的是正确 .p12，再核对 Store Password、Key Password 和 Alias。不要为了绕过错误直接重新生成一套发布密钥。

Profile 与证书不匹配

Profile 创建时选择的不是当前证书，或证书更新后仍在使用旧 Profile。重新生成 Profile，并更新本地与 CI 中的成套材料。

bundleName 不匹配

核对 AppGallery Connect 应用、工程 app 配置、product 配置和 Profile。测试环境配置覆盖正式 bundleName 是常见原因。

调试可运行，Release 构建失败

自动调试签名和手动 Release 签名是两套材料。重点检查 Release product 是否引用正式 signingConfig，以及正式 Profile 是否包含项目需要的能力。

本地成功，CI 失败

检查 CI 文件路径、文件权限、变量注入和当前工作目录。macOS、Windows 与 Linux Runner 的路径处理不同，不要在配置中硬编码本机绝对路径。

HAP 能构建但后台拒绝

除了签名，还要核对版本号、API 级别、设备类型、应用身份、包格式、权限声明和发布 Profile。构建工具成功只说明本地任务完成，不代表商店发布条件全部满足。

到期与轮换策略

证书或 Profile 临近到期时，按并行迁移方式处理：

1. 提前申请新证书。
2. 使用新证书生成新的发布 Profile。
3. 在隔离分支或测试流水线完成 Release 构建。
4. 验证安装、升级、推送、登录和关键服务。
5. 更新生产 CI 凭据。
6. 保留旧材料的受控归档，确认无依赖后再撤销。

不要等到发布当天才发现 Profile 过期。证书到期检查应进入监控或固定巡检清单。

最终检查清单

• bundleName 与后台应用完全一致。
• .p12 中的私钥、Alias 和密码可用。
• 发布证书未过期且用途正确。
• .p7b Profile 绑定当前应用与证书。
• 工程权限、后台能力与 Profile 一致。
• Release product 使用正式 signingConfig。
• HAP 的版本、身份和签名已验证。
• CI 不会输出或长期保留签名材料。
• 密钥、证书、Profile 和密码有受控备份。
• 已完成恢复和轮换演练。

HarmonyOS 签名管理的核心不是记住某个版本的菜单位置，而是始终能回答三个问题：这个 HAP 属于哪个应用、由哪把私钥签名、Profile 允许它使用哪些能力。只要这三件事可追溯，证书问题就能从“反复试配置”变成按链路排查。