84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
# Build & Deploy（构建与部署）
|
||
|
||
构建系统：hvigor（HarmonyOS 官方构建工具），配置见 `hvigor/`、`hvigorfile.ts`、`build-profile.json5`。
|
||
|
||
## 构建 / 运行 Build & Run
|
||
|
||
- **主路径**：DevEco Studio → Build / Run（GUI）。首次打开自动同步依赖。
|
||
- 命令行（`hvigorw` wrapper 由 DevEco 首次同步生成）：
|
||
|
||
```bash
|
||
# 构建 debug HAP
|
||
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
|
||
|
||
# 构建 release HAP
|
||
hvigorw assembleHap --mode module -p product=default -p buildMode=release
|
||
```
|
||
|
||
产物通常在 `entry/build/default/outputs/` 下（`default` 为 product 名）。
|
||
|
||
## 多模块构建 Multi-module Build
|
||
|
||
本工程为「单 HAP + 多 HAR」：`entry/`（HAP）+ `common/`（HAR）+ `uikit/`（HAR）。
|
||
|
||
- HAR（`common`/`uikit`）作为 `entry` 的依赖，构建 entry 时会**自动先编译**依赖的 HAR，正常开发只需构建 entry。
|
||
- 任务类型：HAP 用 `assembleHap`，HAR 用 `assembleHar`。
|
||
- 构建整个工程用 `--mode project`（按依赖顺序构建全部模块）；构建单个模块用 `--mode module`。
|
||
- 模块注册：根 `build-profile.json5` 的 `modules`；模块间依赖：各自 `oh-package.json5` 的 `dependencies` 用 `file:../xxx` 声明。
|
||
|
||
**HAR 配置要点（易错）**：
|
||
- `module.json5` 的 `type` 必须是 `har`（**不是** `shared`——`shared` 对应 HSP，会要求 `hspTasks`）。
|
||
- `oh-package.json5` 的 `main: "Index.ets"` 指向**模块根目录**的 `Index.ets`（该文件 `export * from './src/main/ets/Index.ets'` 转发公共 API）。
|
||
- 权限（如 `ohos.permission.INTERNET`）只声明在 HAP 的 `module.json5` 的 `requestPermissions`；HAR 不声明权限。
|
||
|
||
## 签名 Signing
|
||
|
||
### 现状与原则
|
||
|
||
- `build-profile.json5` 里 `signingConfigs` 在**仓库中必须保持为空 `[]`**（`products[].signingConfig` 仍引用 `"default"`）——签名是机器相关的，禁止入库。
|
||
- 真正的密钥物料（`.p12` / `.cer` / `.p7b`）由 DevEco 生成在 `~/.ohos/config/` 下，**本来就在仓库外**；`build-profile.json5` 里只有「文件路径 + 加密后的密码」，但同样属敏感信息，不得提交。
|
||
|
||
### 本地配置签名（不入库）
|
||
|
||
要跑真机/模拟器需先配置签名：
|
||
- DevEco Studio → File → Project Structure → Signing Configs → 勾选自动签名（登录华为账号）。
|
||
- 或手动配置 `.p12` + `.cer` / `.p7b`。
|
||
|
||
DevEco 自动签名会把凭据写进 `build-profile.json5`，这属于**本地未提交状态**，不要 `git add` 它。
|
||
|
||
### 防泄露：pre-commit 钩子
|
||
|
||
仓库内置了 pre-commit 钩子 `scripts/git-hooks/pre-commit`：只要暂存区的 `build-profile.json5` 出现 `keyPassword` / `storePassword` / `certpath` 等签名字段，就**拒绝提交**。
|
||
|
||
每个克隆启用一次：
|
||
|
||
```bash
|
||
git config core.hooksPath scripts/git-hooks
|
||
```
|
||
|
||
验证：临时在 `build-profile.json5` 里塞一个 `"keyPassword"` 再 `git add build-profile.json5 && git commit`，应被拦截。
|
||
|
||
> 确需临时绕过时用 `git commit --no-verify`（仅应急，不建议）。
|
||
|
||
### 彻底外部化（可选）
|
||
|
||
若想连本地也不出现凭据，可走「动态配置签名」：用 `hvigorfile.ts` 从 gitignore 的本地文件或环境变量读取签名注入，让 `build-profile.json5` 始终保持空。参考华为官方《基于动态配置签名的多人协同开发应用签名解决方案》。
|
||
|
||
> `build-profile.json5` 的签名部分属于 **Agent 禁止修改** 范围（见 `AGENTS.md`）。
|
||
|
||
## 产品与构建模式 Products & Build Modes
|
||
|
||
- `products`：当前只有一个 `default`（`targetSdkVersion 6.0.2(22)`，`runtimeOS: HarmonyOS`）。
|
||
- `buildModeSet`：`debug` / `release`。
|
||
|
||
## 部署 Deploy
|
||
|
||
1. 配置签名（见上）。
|
||
2. 连接真机（开启开发者模式 + USB 调试）或启动模拟器。
|
||
3. DevEco Studio 选择设备 → Run。
|
||
|
||
## 环境环境变量 / 本地配置
|
||
|
||
- `local.properties`：本机 SDK 路径等，**已 gitignore，勿提交，勿写密钥**。
|
||
- 依赖锁：`oh-package-lock.json5`，提交以固定依赖版本。
|