# 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
# 只打印命令，不构建
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`。

## 签名配置

1. 复制 `signing.template.json5` 的 `signingConfigs` 到 `build-profile.json5` 的 `app` 节点；
2. 证书与密码通过环境变量/密钥库注入，**不得提交到仓库**；
3. 未配置签名时构建仍可成功，但产物为 `*-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 个版本 + 所有里程碑版本。