1.2 构建、HAP 产物与签名体系

1.2 构建、HAP 产物与签名体系

本节摘要：拆解 1.1 节里"照做"过的构建与签名环节：hvigor 如何理解工程、HAP 包里装了什么、证书与 Profile 如何构成签名体系。读完你能读懂构建配置文件，并手动完成一次签名打包。

一次构建背后发生了什么

上一节点了运行按钮，工程就变成了模拟器里的应用——中间那几秒发生的事，是本节的主角。HarmonyOS 工程的构建工具叫 hvigor，前端基于 Node 生态，任务模型类似前端开发者熟悉的构建流水线：解析配置、编译 ArkTS、处理资源、打包、签名。它读两个层级的配置：

• 工程根目录的 build-profile.json5：管全局——签名配置、模块列表、产品维度（比如 debug 与 release 的差异项）。
• 每个模块（entry 是默认的应用主模块）里的 module.json5 与自己的 build-profile.json5：管这个模块的能力声明、设备类型、依赖。

点运行时实际执行的是 assembleHap 任务的调试版本。你在日志里看到的一串输出，就是 hvigor 依次执行各任务的过程。理解到"构建 = 按配置跑任务流水线"这个程度就够用了，重要的是知道去哪改配置：改签名去工程级 build-profile.json5，改应用图标名称去 AppScope 下的 app.json5，改页面与权限去模块的 module.json5。

构建的产物是 HAP（Harmony Ability Package）。一个应用可以由多个 HAP 组成：entry 类型的是主模块，feature 类型的是按需加载的功能模块；最终上架时它们会被整合进一个 App Pack（后缀 .app）。包内结构值得看一眼：

图：HAP 包内结构一览

可以直接验证：在工程构建输出目录里找到 debug 版 HAP 文件，把后缀改成 zip 解压，上面这些目录就摊开在眼前。亲手解一次包，比读十遍文档的印象深。

签名体系：为什么绕不开

签名要解决的问题是身份与完整性：系统需要确认这个包确实来自你，且从打包到安装没被改过。体系由三样东西构成——开发者证书（证明"你是谁"）、Profile 文件（证明"这个应用被授权做什么"，含包名、权限、能装的设备列表）、密钥库文件（保存私钥，绝不外传）。调试场景下 DevEco Studio 会自动生成一整套，这就是 1.1 节排错时遇到的 "Automatically generate signature" 背后的机制。

现在动手看一眼这套自动签名落在哪。打开工程级 build-profile.json5，找到 signingConfigs 段，大致长这样：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "material": {
          "certpath": "C:/Users/you/.ohos/config/default_xxx.pem",
          "storePassword": "000000xx...",
          "keyAlias": "debugKey",
          "profile": "C:/Users/you/.ohos/config/default_xxx.p7b",
          "signAlg": "SHA256withECDSA"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default"
      }
    ]
  }
}
​

certpath 指向证书、profile 指向授权描述文件，product 再把签名配置挂到构建产品上。自动签名帮你填好了这些路径；将来上架时（第 8 章），你要在华为的 AppGallery Connect 平台申请发布证书与 Profile，手动替换到这里。

动手：命令行构建一次

IDE 里的按钮终究是封装。在工程根目录打开终端，执行：

hvigorw assembleHap --mode module -p product=default
​

输出目录里会多出新的 HAP 文件。把它通过 IDE 的安装功能装进模拟器——成功，说明你已能在没有图形界面按钮的情况下完成构建；这条命令也是后续自动化流水线（比如每日构建、打渠道包）的起点。再试一次 release 模式：

hvigorw assembleHap --mode module -p buildMode=release
​

若没有配置 release 签名，这一步会失败并提示签名缺失——这正是调试与发布签名的分界线在起作用。别急着修，记住这个报错的样子，第 8 章会带着发布证书回来解决它。

⚠️ 常见坑：把带私钥的签名材料提交进代码仓库。正确做法是把 signingConfigs 里指向的密钥文件加入忽略清单，团队成员各自用调试签名，发布签名只保留在打包机上。

💡 关键直觉：把 build-profile.json5 理解成"工程的户口与门禁"——户口决定有哪些模块和产品，门禁决定谁能被安装。改任何构建相关的行为，先来这里找，而不是满工程搜配置。

本节要点回顾：

• 构建链路：hvigor 按工程级与模块级两级配置执行任务流水线，产物是 HAP。
• 两个关键文件：工程级 build-profile.json5 管签名与产品；模块级 module.json5 管能力与权限声明。
• HAP 结构：配置、ArkTS 产物、资源（可含 native 库）打包成 zip 形态的 HAP，多 HAP 组成最终上架的 App Pack。
• 签名三件套：证书、Profile、密钥库；调试自动、发布手动，上架是分水岭。
• 排错锚点：安装失败先看签名，构建失败先看配置与网络。

到本章为止，环境与工具链都是背景板。下一章我们正式进入工程内部：Stage 模型给了工程一副什么样的骨架，以及如何亲手写下第一个 ArkTS 页面。

附：构建提速与仓库卫生

工程变大后构建会从几秒涨到几十秒，两个立竿见影的手段现在就可以了解。一是增量构建：hvigor 默认只重编变化的模块，所以别动不动全量重建——Clean 只在依赖结构变化（加减模块、升 SDK）后才需要。二是命令行并行参数：多核机器收益明显，IDE 里默认开启，自动化流水线才要手动加。构建缓存目录会随时间膨胀，磁盘紧张时定期清理，代价只是下一次首次构建变慢。

仓库卫生同样值得十秒钟确认：构建产物目录必须在版本管理的忽略清单里。曾有团队把产物目录整个提交进仓库，每次构建后出现成百上千个无意义变动，代码评审彻底没法看。检查忽略配置、把签名材料一并排除（前文已述），这两件事做完，工程的第一天就算是干净的。