初始化项目

2026-10-19 00:11:38 +08:00
commit 9545e48e4d
150 changed files with 9559 additions and 0 deletions
@@ -0,0 +1,60 @@
+# 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 个版本 + 所有里程碑版本。