CI 构建与签名流水线（1.3.11）
本目录把「命令行构建 → 签名 → 产物归档」固化为可复用脚本与流水线说明。
前置环境
| 项 | 要求 | 说明 |
|---|---|---|
| JDK | 17（JAVA_HOME） |
hvigor 依赖 |
| Node | 22.19+ / 24 | hvigor 与 ohpm |
| 命令行工具 | command-line-tools（hvigorw / ohpm / sdk） |
与 DevEco Studio 版本一致 |
| SDK | DEVECO_SDK_HOME 指向 SDK 根目录 |
当前 API 24（6.1.1.125） |
| 签名材料 | .p12、.cer、.p7b |
由 AGC 申请，只注入 CI 密钥库 |
流水线阶段
① 检出代码
② ohpm install --all（锁定 lockfile）
③ 静态检查：ArkTS 编译 + code-linter（hvigorw 内置）
④ 构建：ci/build-hap.ps1 -BuildMode debug|release
⑤ 签名：注入签名配置（见 signing.template.json5），hvigorw 重新打包签名
⑥ 归档：HAP/APP、mapping、符号表，保留最近 N 次
⑦ 分发：上传 AGC（发布通道 / 测试通道）
本地用法
# 只打印命令，不构建
powershell -ExecutionPolicy Bypass -File ci\build-hap.ps1 -DryRun
# 调试构建
powershell -ExecutionPolicy Bypass -File ci\build-hap.ps1 -BuildMode debug
# 发布构建（需先配置 signingConfigs）
powershell -ExecutionPolicy Bypass -File ci\build-hap.ps1 -BuildMode release
产物定位：entry\build\<product>\outputs\<product>\*.hap。
签名配置
- 复制
signing.template.json5的signingConfigs到build-profile.json5的app节点； - 证书与密码通过环境变量/密钥库注入，不得提交到仓库；
- 未配置签名时构建仍可成功，但产物为
*-unsigned.hap，无法真机安装。
已知问题
| 现象 | 原因 | 处理 |
|---|---|---|
EPERM: operation not permitted, symlink ... |
hvigor 需要在工作区外创建工具链接；受限沙箱会拒绝 | CI 运行在完整权限环境；本地不要在受限沙箱执行 |
No signingConfigs profile is configured |
未配置签名 | 按上节注入签名配置 |
version ... does not comply with SemVer |
oh-package 版本主版本号为 0 | 模块版本使用 1.x.y |
版本与产物保留
versionCode单调递增，versionName语义化；- 每个发布版本归档：HAP、mapping、混淆符号表、构建日志；
- 保留策略：最近 10 个版本 + 所有里程碑版本。