在这里插入图片描述

你是不是也在想——“鸿蒙这么火,我能不能学会?”
答案是:当然可以!
这个专栏专为零基础小白设计,不需要编程基础,也不需要懂原理、背术语。我们会用最通俗易懂的语言、最贴近生活的案例,手把手带你从安装开发工具开始,一步步学会开发自己的鸿蒙应用。
不管你是学生、上班族、打算转行,还是单纯对技术感兴趣,只要你愿意花一点时间,就能在这里搞懂鸿蒙开发,并做出属于自己的App!
📌 关注本专栏《零基础学鸿蒙开发》,一起变强!
每一节内容我都会持续更新,配图+代码+解释全都有,欢迎点个关注,不走丢,我是小白酷爱学习,我们一起上路 🚀

前言

第一次在 DevEco Studio 里点"自动签名",往往只是等它转一圈、弹出"签名配置成功"就跑去运行了。但只要换了一台电脑、换了一个华为账号、换了一台调试设备,问题就来了:为什么新机器装不上?为什么换了台手机就提示签名校验失败?为什么把工程发给同事,他直接编译就跑不起来?

这些问题,答案几乎都藏在自动签名生成的那几个文件里。把这条签名链路弄清楚,后面很多折腾不清楚的问题自然就有头绪了。

一、自动签名做了什么事

DevEco Studio 的"自动签名"(Automatically generate signature)并不是在本地随便生成几个文件,它实际上完成了一套完整的证书申请和配置流程,背后依赖的是 AppGallery Connect(AGC)的证书管理体系。

整个过程大致是这样的:

  1. DevEco Studio 在本地生成一对密钥(非对称密钥对);
  2. 把公钥部分上传给 AGC,由华为的 CA(证书颁发机构)对这个公钥签发一张开发者证书;
  3. 把签发好的证书和私钥打包成一个 .p12 文件,存在本地;
  4. 同时把证书单独导出,保存成 .cer 文件;
  5. 根据当前工程的 bundleName 和已注册的调试设备 UDID,从 AGC 下载对应的 HarmonyAppProvision 文件,也就是 .p7b 文件;
  6. 在 build-profile.json5 里自动写入上述三个文件的路径和密码配置。

所以"一次点击"背后,实际上是本地密钥生成、CA 证书签发、Profile 下载三件事合在一起完成。

二、三个文件分别是什么

.p12 — 私钥和证书的容器

.p12 是 PKCS#12 格式的密钥库文件。它同时包含两样东西:开发者私钥和对应的开发者证书。

之所以打包在一起,是因为签名操作需要两者配合:私钥用来对应用包做签名计算,证书用来让系统验证这个私钥确实属于某个经过 CA 认证的开发者身份。

.p12 有一个访问密码,丢失密码就无法再从中提取私钥。这个文件和密码应该一起妥善保存,不应该随工程代码一起提交到版本库。

.cer — 开发者证书

.cer 是从 .p12 中单独提取出来的证书部分,里面不含私钥,是华为 CA 签发的公开证书。

HarmonyOS 的证书体系是三层结构:

华为设备根 CA
  └── 华为应用子 CA
        └── 开发者证书(即 .cer 文件)

系统在验证应用签名时,会沿着这条链从开发者证书一路验证到根 CA,确认整条链是可信的。.cer 文件就是这条链最末端那一环。

调试证书(通过自动签名生成的)和发布证书在结构上是相同的,区别在于它们在 AGC 上的证书类型不同,对应 Profile 中的 type 字段也不同(debug vs release)。

.p7b — HarmonyAppProvision(Profile)

这是三个文件里最容易被忽视、但实际上对调试影响最直接的一个。

.p7b 是 PKCS#7 格式的签名数据容器,里面封装的是 HarmonyAppProvision 文件的 JSON 内容,由华为 CA 对其整体做了签名,确保内容不被篡改。

Profile 的 JSON 结构中包含以下关键字段(根据官方文档):

  • bundle-info:绑定的 bundleName 和应用相关标识
  • acls:应用可以申请使用的高敏感权限列表
  • permissions:应用被授予的权限
  • debug-info:调试签名下允许安装该包的设备 UDID 列表
  • validity:Profile 的有效期(开始时间和结束时间)
  • type:debug 或 release

这个文件打包进 .hap 之后,系统在安装时会校验:当前设备的 UDID 是否在 debug-info 里,包名是否与 bundle-info 里的一致,签名证书是否和 Profile 绑定的一致。三项都对,安装才能成功。

三、bundleName 是怎么绑进去的

bundleName 在 HarmonyOS 里是应用的唯一标识,一旦在 AGC 上创建了应用,这个名称就不能随意更改。

自动签名在下载 Profile 时,会根据当前 AppScope/app.json5 里配置的 bundleName 去 AGC 匹配已经创建的应用,然后把这个 bundleName 写进 Profile 的 bundle-info 中。

// AppScope/app.json5(片段)
{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0"
  }
}

如果本地工程的 bundleName 和 AGC 上没有对应的应用记录,自动签名就会在 AGC 上先帮你创建这个应用再生成 Profile。这是很多开发者不注意的地方:本地改了 bundleName 之后没有重新触发自动签名,导致 Profile 里的 bundleName 和工程实际 bundleName 对不上,安装时直接失败。

四、调试设备是怎么注册进去的

调试签名的 Profile 只允许安装到 debug-info.device-ids 列表里的设备。这个列表在 AGC 上管理,存的是设备的 UDID。

自动签名会把当前通过 USB 连接 DevEco Studio 的设备 UDID 自动上报到 AGC,然后下载包含该 UDID 的新版 Profile。

这意味着:

  • 换了一台新调试设备,需要在 DevEco Studio 里重新触发自动签名(或在 AGC 控制台手动添加 UDID 并重新下载 Profile);
  • 把 .p7b 文件直接复制给同事是不够的,因为他的设备 UDID 不在你的 Profile 里;
  • 每次 AGC 上的 Profile 有变动(比如添加新设备),都需要重新下载 .p7b,工程里配置的 Profile 文件才会生效。

五、build-profile.json5 里的配置是怎么接起来的

自动签名配置完成后,build-profile.json5 里会新增一个 signingConfigs 块,大概是这样的结构:

// build-profile.json5(片段,仅展示签名相关字段结构)
{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "certpath": "路径/xxx.cer",
          "storePassword": "加密后的密码",
          "keyAlias": "debugKey",
          "keyPassword": "加密后的密码",
          "profile": "路径/xxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "路径/xxx.p12"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default"
      }
    ]
  }
}

几点值得注意:

  • storePassword 和 keyPassword 在文件里是经过 DevEco Studio 加密处理的字符串,不是明文。不同机器上的加密结果不同,所以这个文件直接复制到另一台机器是用不了的;
  • signAlg 目前 HarmonyOS 调试签名使用 SHA256withECDSA;
  • certpath、profile、storeFile 三个路径默认指向工程目录下 .signing 文件夹里的文件。

六、几个容易出问题的地方

1. 修改了 bundleName 但没有重新签名

app.json5 里的 bundleName 改了之后,.p7b 里绑定的仍然是旧的名称,安装时系统校验 bundleName 不一致,直接拒绝。解决方法是重新触发一次自动签名,让 DevEco Studio 重新从 AGC 下载新的 Profile。

2. 换了调试设备但 Profile 没有更新

新设备的 UDID 不在 Profile 里,安装会提示签名校验失败。这里很容易把问题归到签名文件损坏或者证书有问题,实际上只需要重新自动签名一次,让新设备 UDID 被写进 Profile 即可。

3. 把签名文件一起提交了 Git,换机器克隆后编译失败

前面提到,storePassword 和 keyPassword 是机器级别加密的。把整个签名配置提交到 Git 之后,另一台机器拿到的是无法解密的密码字段,编译时会报密码错误。建议在 .gitignore 里忽略 .signing 目录,团队协作时每人在自己账号下各自自动签名即可。

4. 调试证书过期

自动签名生成的调试证书是有有效期的。证书到期后 AGC 那边的证书状态会变成无效,需要在 AGC 控制台重新申请或者重新触发自动签名刷新证书。build-profile.json5 里的 .cer 文件路径不变,但文件内容是旧的,续期后需要重新下载。

5. 多 Module 工程只给一个 Module 配置了签名

HarmonyOS 工程如果有多个 Module(Feature HAP、Entry HAP),每个需要安装到设备的 HAP 都需要签名。如果只在 Entry Module 上配了签名,其他 HAP 打包时没有签名,安装会失败或者行为不符合预期。build-profile.json5 里 modules 下每个条目都可以单独指定 signingConfig,或者统一使用 app 级别的默认配置。

七、排查顺序建议

遇到安装失败、签名报错,按这个顺序检查往往能更快定位:

  1. 确认 bundleName 是否一致 — app.json5 里的值和 AGC 应用记录,以及 Profile 里绑定的值,三者是否相同;
  2. 确认设备 UDID 是否在 Profile 里 — 去 AGC 控制台的 Profile 详情里看设备列表;
  3. 确认证书是否在有效期内 — AGC 控制台的证书管理里可以查状态;
  4. 确认签名文件是否匹配当前机器 — 如果是从别人那里拿来的 build-profile.json5,密码字段是无效的,需要重新配置;
  5. 确认所有需要安装的 HAP 都有签名配置 — 检查 build-profile.json5 里每个 module 的 signingConfig 指向是否正确;
  6. 重新触发一次自动签名 — 以上排查都没问题,最直接的方式是让 DevEco Studio 重新走一遍自动签名流程,确保本地文件和 AGC 上的配置保持同步。

开发经验总结

  • .p12 是私钥和证书的打包容器,丢失密码就无法再使用;.cer 是证书的单独导出;.p7b 是 Profile,绑定了 bundleName、设备 UDID 和权限,对调试安装影响最直接。
  • 自动签名的本质是:本地生成密钥 → AGC 签发证书 → 下载绑定了当前设备和包名的 Profile,三步合一。
  • 换设备、改 bundleName、换账号,都需要重新触发自动签名,单独复制文件很难解决问题。
  • .signing 目录和 build-profile.json5 中的密码字段不适合纳入版本库,团队各自在自己账号下走一遍自动签名是更稳妥的协作方式。
  • 调试证书有有效期,AGC 上证书到期后需要重新申请,不是一次配置永久有效。

如果你正在多人协作的项目里遇到签名问题,可以重点看一下每个人的 AGC 账号下是否有这个 bundleName 对应的应用记录——有时候 bundleName 是在另一个成员账号下创建的,其他人自动签名时会重新在自己账号下创建一个同名应用,Profile 里绑定的是不同的应用记录,这类问题不仔细对比 AGC 控制台很难发现。

❤️ 如果本文帮到了你…

  • 请点个赞,让我知道你还在坚持阅读技术长文!
  • 请收藏本文,因为你以后一定还会用上!
  • 如果你在学习过程中遇到bug,请留言,我帮你踩坑!
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐