HarmonyKit | 鸿蒙开发：应用签名与证书管理完全指南

发布时间：2026/7/11 19:37:44

HarmonyKit | 鸿蒙开发：应用签名与证书管理完全指南

引言：签名是鸿蒙应用安全的第一道防线

如果你从 Android 开发转过来，鸿蒙的签名体系会让你感到既熟悉又陌生。熟悉的是.p12、.cer、签名算法这些概念——它们背后是通用的 PKI（公钥基础设施）。陌生的是.p7b文件（Provisioning Profile）——这是鸿蒙特有的概念，它连接了应用、设备和权限，构建了一个远比 Android 签名更精细的安全模型。

这篇文章从 HarmonyKit 的实际签名配置出发，逐一解释调试证书的自动生成机制、三种证书文件的角色、签名的完整流程、生产环境签名的配置方式，以及最常见的签名相关错误与解决方案。

项目仓库：https://atomgit.com/VON-/harmony-kit

HarmonyKit 的签名配置

HarmonyKit 目前的签名配置使用 DevEco Studio 自动生成的调试证书：

{ "signingConfigs": [ { "name": "default", "type": "HarmonyOS", "material": { "certpath": "/Users/wangxinjie/.ohos/config/default_harmonykit_ILWFj4Nj-Tk46D_IPIOnA9MssH0d-cMIIkhqzo-5PhQ=.cer", "keyAlias": "debugKey", "keyPassword": "0000001A9C26AE5EA7A8E394442AC6FFB81D7F7AFA35805AC58960D735B9DFA3BAE144F68AADC4287472", "profile": "/Users/wangxinjie/.ohos/config/default_harmonykit_ILWFj4Nj-Tk46D_IPIOnA9MssH0d-cMIIkhqzo-5PhQ=.p7b", "signAlg": "SHA256withECDSA", "storeFile": "/Users/wangxinjie/.ohos/config/default_harmonykit_ILWFj4Nj-Tk46D_IPIOnA9MssH0d-cMIIkhqzo-5PhQ=.p12", "storePassword": "0000001AA11F49C6DB4ECC2BBCBC40B96975FE70578290DE891D989C73132FC99B5DD578410FBC95B73C" } } ] }

一眼望去，六个路径/字段组成了签名配置的核心。让我们逐一解读。

三个核心证书文件的角色

.p12 文件（storeFile）：密钥的保险箱

.p12（PKCS#12）文件是一个加密容器，内部存放着开发者的私钥和证书链。它是整个签名体系中最敏感的文件——谁拥有.p12文件和密码，谁就能以你的身份签署应用。

HarmonyKit 的调试.p12文件存储在~/.ohos/config/目录下，文件名包含项目的哈希值。密码是 DevEco Studio 自动生成的 72 位十六进制字符串。

调试.p12的生成流程：

首次在 DevEco Studio 中运行项目
IDE 检测到没有签名配置，自动触发签名向导
生成一个自签名的根证书和开发密钥对
私钥存储在.p12文件中，密码自动生成
公钥导出为.cer证书

生产环境的.p12管理：

调试.p12由 IDE 自动管理、自动续期、自动备份。但生产环境需要你自己管理.p12文件。关键注意事项：

不要将.p12提交到源码仓库。即使密码很强，私钥泄露等于应用身份被盗。
在 CI/CD 中通过环境变量或加密的 Secret 管理。如 GitHub Actions 的 Secrets、GitLab CI 的 Variables。
备份.p12和密码。丢失.p12或忘记密码意味着你无法为同一应用签名——在 AppGallery 上，这等于永远无法更新该应用。
.p12有效期：生产证书有有效期（通常 1-2 年），过期后需要重新申请。但续期证书应使用相同的密钥对，否则系统会将其视为全新应用。

.cer 文件（certpath）：应用的身份证书

.cer（Certificate）文件是 X.509 格式的数字证书，包含开发者的公钥和身份信息。在签名体系中，.cer是"公开"部分——它被嵌入到签名后的 HAP 中，供设备验证签名的真实性。

验证流程：设备拿到 HAP 后，提取其中的.cer证书，用证书中的公钥解密 HAP 的签名值，对比哈希值是否匹配。匹配则签名有效。

对于调试证书，.cer是自签名的（不受信任的 CA 签发）。设备信任它是因为调试证书通过 Provisioning Profile 被注册到了设备的信任列表中。

对于生产证书，.cer由 AppGallery 的 CA 签发，是正式的、可验证的身份证书。

.p7b 文件（profile）：Provisioning Profile

.p7b文件（PKCS#7 Binary）是鸿蒙签名体系中最特殊的部分。它类似于 iOS 的 Provisioning Profile（实际上鸿蒙借鉴了 iOS 的安全模型），描述了以下权限绑定关系：

应用身份（bundleName）：哪个应用可以使用此 profile
设备列表（device IDs）：哪些设备可以安装并运行此应用
证书绑定（certificate）：哪个开发证书可以使用此 profile 签名
权限声明（permissions）：应用获得了哪些受保护的权限
能力声明（capabilities）：应用需要哪些系统能力

调试 profile 由 DevEco Studio 自动生成，通常绑定到当前连接的调试设备。生产 profile 在 AppGallery Connect 中手动配置。

Provisioning Profile 的工作原理：

当你将调试 HAP 安装到设备时：

设备从 HAP 中提取 Provisioning Profile
设备验证 profile 中的设备列表是否包含自己（不在列表中的设备拒绝安装）
设备验证 profile 中的 bundleName 是否与 HAP 的 bundleName 一致
设备验证用于签名的证书是否在 profile 允许的证书列表中
所有验证通过后，应用被安装

这套机制确保了：

未经你授权的设备无法安装你的调试版本（防止测试包泄露）
未经授权的开发者无法用他们的证书给你的应用签名
未声明的权限不会在运行时生效

签名算法的选择

HarmonyKit 使用SHA256withECDSA签名算法。这让它由两个部分组成：

ECDSA（Elliptic Curve Digital Signature Algorithm）：基于椭圆曲线的数字签名算法。与 RSA 相比，ECDSA 提供同等级别的安全性但使用更短的密钥——256 位的 ECDSA 安全性相当于 3072 位的 RSA。更短的密钥意味着更小的签名值，更少的计算开销。

SHA-256：签名过程中用于计算哈希值的哈希算法。应用的原始数据先经过 SHA-256 哈希（产生一个固定长度的摘要），然后对该摘要使用 ECDSA 私钥进行签名。

鸿蒙支持的签名算法包括：

SHA256withECDSA（最常用，推荐）
SHA256withRSA
SHA384withECDSA
SHA384withRSA

一般选择SHA256withECDSA即可。更高的 SHA 位数（384）提供更强的安全性但带来更大的签名开销，对应用签名来说没有实际必要。

调试签名的自动管理机制

DevEco Studio 的调试签名自动管理是它最方便的特性之一。但理解它的内部机制能在遇到问题时快速定位：

首次运行触发：项目第一次在 DevEco Studio 中运行时，IDE 检测build-profile.json5中没有有效签名配置，弹出"自动生成签名"对话框。
证书存储位置：自动生成的证书文件存放在~/.ohos/config/目录下。文件命名格式为{projectType}_{projectName}_{hash}。换一台电脑或删除该目录，证书就丢失了。
设备注册：连接调试设备后，DevEco Studio 会自动将设备的 UDID 注册到 Provisioning Profile 中。换一台新设备需要重新注册——IDE 通常会弹窗提示"是否为此设备注册调试配置"。
证书过期：调试证书的有效期通常是 1 年。到期前 DevEco Studio 会提示更新。更新操作会生成新的密钥对和证书，旧的已安装应用不受影响。
多设备调试：如果你同时连接了手机和平板，DevEco Studio 会将两个设备的 UDID 都写入 Provisioning Profile。每个设备有自己唯一的 UDID，确保只有你指定的设备可以运行调试版本。

生产签名与 AppGallery 上架

当 HarmonyKit 准备上架 AppGallery 时，需要一套全新的签名流程：

Step 1: 在 AppGallery Connect 创建应用

在 AppGallery Connect 网站创建应用，填写 bundleName（必须与app.json5中的bundleName完全一致）、应用名称、类别等信息。

Step 2: 生成/上传签名证书

AppGallery Connect 提供两种选择：

方案 A：让 AppGallery 生成证书

优点：不需要手动管理密钥，AppGallery 托管私钥安全存储
缺点：你必须使用 AppGallery 生成的证书，无法自行控制密钥生命周期

方案 B：上传你自己的证书

优点：完全控制密钥，支持企业已有的证书体系
缺点：需要自己保管.p12私钥和密码，丢失即无法更新应用

对于个人开发者，AppGallery 代管证书是最简单的选择。对于企业，可能已有 PKI 体系，更倾向于上传自己的证书。

Step 3: 配置 Provisioning Profile

生产环境需要手动配置 Provisioning Profile，包含：

选择证书：绑定 Step 2 中的签名证书
声明权限：列出应用需要使用的敏感权限（如位置、相机、通讯录等）
声明能力：列出应用需要的系统能力（如推送、分析、支付等）
设备范围：调试 profile 绑定特定设备，生产 profile 通常不限制设备范围（所有设备可安装）

Step 4: 更新 build-profile.json5

将生产签名配置添加到signingConfigs数组：

"signingConfigs": [ { "name": "debug", // 保留调试配置 "type": "HarmonyOS", "material": { /* 自动生成的调试证书 */ } }, { "name": "release", // 新增生产配置 "type": "HarmonyOS", "material": { "certpath": "./keystore/release.cer", "keyAlias": "releaseKey", "keyPassword": "你的密钥密码", "profile": "./keystore/release.p7b", "signAlg": "SHA256withECDSA", "storeFile": "./keystore/release.p12", "storePassword": "你的密钥库密码" } } ]

同时更新 products 配置，为不同构建模式使用不同签名：

"products": [ { "name": "default", "signingConfig": "debug", // 日常开发用 debug 签名 // ... }, { "name": "release", "signingConfig": "release", // 发布用 release 签名 // ... } ]

构建时选择 release product：

hvigorw assembleHap-pproduct=release-pbuildMode=release

签名相关常见错误及修复

错误一：设备不在 Provisioning Profile 允许列表中

现象：

ERROR: Failed to install HAP. The device is not authorized. ERROR: Provisioning profile does not contain this device.

原因：连接了新的调试设备，但该设备的 UDID 还没有被注册到调试 Provisioning Profile 中。

修复：

在 DevEco Studio 中连接设备
IDE 会弹出"允许此设备进行调试?"对话框
点击"允许"，IDE 自动将设备 UDID 添加到 profile 中
重新运行项目

错误二：证书已过期

现象：

ERROR: The certificate has expired.

原因：调试证书有效期通常为 1 年，到期后需要更新。

修复：

DevEco Studio > Build > Generate Key and CSR
或：删除~/.ohos/config/目录下对应项目的证书文件
重新运行项目让 IDE 自动生成新证书

错误三：签名密码不匹配

现象：

ERROR: Keystore was tampered with, or password was incorrect.

原因：.p12文件的密码与配置不一致。可能发生在更换了证书文件但没有更新密码配置的情况下。

修复：

确认storePassword和keyPassword是否正确
如果密码确实丢失，只能重新生成证书
删除旧的.p12、.cer、.p7b文件，让 IDE 重新生成

错误四：跨电脑协作的签名问题

现象：从 Git 拉取项目后，构建失败，报签名相关错误。

原因：证书文件的绝对路径（~/.ohos/config/...）指向了另一台电脑的文件系统，当前电脑上不存在这些文件。

修复（三人团队推荐方案）：

将证书文件放在项目内部（不提交到 Git）：

# 创建本地 keystore 目录（已在 .gitignore 中）mkdir-pkeystore# 在 build-profile.json5 中使用相对路径"certpath":"./keystore/debug.cer","storeFile":"./keystore/debug.p12","profile":"./keystore/debug.p7b"

通过安全渠道共享证书（如加密邮件、密码管理器），每个开发者将证书放到本地keystore/目录。
确保.gitignore包含 keystore 目录：

/keystore/

对于较大的团队，建议每个开发者使用自己的调试证书（让 IDE 自动生成），只在 CI/CD 流程中使用共享的生产签名配置。

错误五：bundleName 与 Provisioning Profile 不匹配

现象：

ERROR: The bundleName in the HAP does not match the profile.

原因：修改了AppScope/app.json5中的bundleName，但签名用的 Provisioning Profile 仍然是基于旧 bundleName 生成的。

修复：重新生成签名配置。bundleName 变更是一个"重大变更"——系统将新 bundleName 的应用视为一个全新应用。

签名安全的最佳实践

1. 密钥分级管理

调试密钥：允许每个开发者生成自己的，不集中管理
测试密钥：CI/CD 环境使用专用的测试密钥（与个人开发者的调试密钥分离）
生产密钥：仅限极少数人持有，通过加密的 Secret 管理

2. .gitignore 必须包含签名相关路径

HarmonyKit 的.gitignore虽然没有显式列出证书文件，但已经通过忽略整个/entry/build/排除了构建产物。建议显式添加：

/keystore/ *.p12 *.cer *.p7b

3. CI/CD 中的签名处理

在 CI/CD 流水线中，签名配置不应该以明文形式存在。推荐做法：

# GitHub Actions 示例- name: Setup Signing Configuration run:|echo"${{ secrets.KEYSTORE_BASE64 }}"|base64-d>keystore/release.p12echo"${{ secrets.CERTIFICATE }}">keystore/release.cerecho"${{ secrets.PROFILE }}">keystore/release.p7b