180 lines
5.6 KiB
Markdown
180 lines
5.6 KiB
Markdown
# Hvigor 命令行构建工具 (hvigorw)
|
||
|
||
hvigorw 是 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。
|
||
|
||
## 命令格式
|
||
|
||
```bash
|
||
hvigorw [taskNames...] <options>
|
||
```
|
||
|
||
## 编译构建任务
|
||
|
||
| 任务 | 说明 |
|
||
|------|------|
|
||
| `clean` | 清理构建产物 build 目录 |
|
||
| `assembleHap` | 构建 Hap 应用 |
|
||
| `assembleApp` | 构建 App 应用 |
|
||
| `assembleHsp` | 构建 Hsp 包 |
|
||
| `assembleHar` | 构建 Har 包 |
|
||
| `collectCoverage` | 基于打点数据生成覆盖率统计报表 |
|
||
|
||
## 常用构建参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `-p buildMode={debug\|release}` | 指定构建模式。默认：Hap/Hsp/Har 为 debug，App 为 release |
|
||
| `-p debuggable=true/false` | 覆盖 buildOption 中的 debuggable 配置 |
|
||
| `-p product={ProductName}` | 指定 product 进行编译，默认为 default |
|
||
| `-p module={ModuleName}@{TargetName}` | 指定模块及 target 编译（需配合 `--mode module`） |
|
||
| `-p ohos-test-coverage={true\|false}` | 执行测试框架代码覆盖率插桩编译 |
|
||
| `-p parameterFile=param.json` | 设置 oh-package.json5 的参数配置文件 |
|
||
|
||
## 构建示例
|
||
|
||
```bash
|
||
# 清理构建产物
|
||
hvigorw clean
|
||
|
||
# Debug 模式构建 Hap
|
||
hvigorw assembleHap -p buildMode=debug
|
||
|
||
# Release 模式构建 App
|
||
hvigorw assembleApp -p buildMode=release
|
||
|
||
# 构建指定 product
|
||
hvigorw assembleHap -p product=free
|
||
|
||
# 构建指定模块
|
||
hvigorw assembleHap -p module=entry@default --mode module
|
||
|
||
# 构建多个模块
|
||
hvigorw assembleHar -p module=library1@default,library2@default --mode module
|
||
```
|
||
|
||
## 测试命令
|
||
|
||
### Instrument Test (设备测试)
|
||
|
||
```bash
|
||
hvigorw onDeviceTest -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
|
||
```
|
||
|
||
- `module`: 执行测试的模块，缺省执行所有模块
|
||
- `coverage`: 是否生成覆盖率报告，默认 true
|
||
- `scope`: 测试范围，格式 `{suiteName}#{methodName}` 或 `{suiteName}`
|
||
- `ohos-debug-asan`: 是否启用 ASan 检测，默认 false (5.19.0+)
|
||
|
||
**输出路径:**
|
||
- 覆盖率报告: `<module-path>/.test/default/outputs/ohosTest/reports`
|
||
- 测试结果: `<project>/<module>/.test/default/intermediates/ohosTest/coverage_data/test_result.txt`
|
||
|
||
### Local Test (本地测试)
|
||
|
||
```bash
|
||
hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
|
||
```
|
||
|
||
**输出路径:**
|
||
- 覆盖率报告: `<module-path>/.test/default/outputs/test/reports`
|
||
- 测试结果: `<project>/<module>/.test/default/intermediates/test/coverage_data/test_result.txt`
|
||
|
||
## 日志级别
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `-e, --error` | 设置日志级别为 error |
|
||
| `-w, --warn` | 设置日志级别为 warn |
|
||
| `-i, --info` | 设置日志级别为 info |
|
||
| `-d, --debug` | 设置日志级别为 debug |
|
||
| `--stacktrace` | 开启打印异常堆栈信息 |
|
||
|
||
## 构建分析 (Build Analyzer)
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `--analyze=normal` | 普通模式分析 |
|
||
| `--analyze=advanced` | 进阶模式，更详细的任务耗时数据 |
|
||
| `--analyze=ultrafine` | 超精细化模式，ArkTS 编译详细打点 (6.0.0+) |
|
||
| `--analyze=false` | 不启用构建分析 |
|
||
| `--config properties.hvigor.analyzeHtml=true` | 生成 HTML 可视化报告到 `.hvigor/report` |
|
||
|
||
## 守护进程 (Daemon)
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `--daemon` | 启用守护进程 |
|
||
| `--no-daemon` | 关闭守护进程（命令行模式推荐） |
|
||
| `--stop-daemon` | 关闭当前工程的守护进程 |
|
||
| `--stop-daemon-all` | 关闭所有工程的守护进程 |
|
||
| `--status-daemon` | 查询所有 Hvigor 守护进程信息 |
|
||
| `--max-old-space-size=12345` | 设置老生代内存大小 (MB) |
|
||
| `--max-semi-space-size=32` | 设置新生代半空间大小 (MB, 5.18.4+) |
|
||
|
||
## 性能与内存优化
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `--parallel` / `--no-parallel` | 开启/关闭并行构建（默认开启） |
|
||
| `--incremental` / `--no-incremental` | 开启/关闭增量构建（默认开启） |
|
||
| `--optimization-strategy=performance` | 性能优先模式，加快构建但占用更多内存 (5.19.2+) |
|
||
| `--optimization-strategy=memory` | 内存优先模式（默认）(5.19.2+) |
|
||
|
||
## 公共命令
|
||
|
||
| 任务 | 说明 |
|
||
|------|------|
|
||
| `tasks` | 打印工程各模块包含的任务信息 |
|
||
| `taskTree` | 打印工程各模块的任务依赖关系 |
|
||
| `prune` | 清除 30 天未使用的缓存并删除 pnpm 未引用包 |
|
||
| `buildInfo` | 打印 build-profile.json5 配置信息 (5.18.4+) |
|
||
|
||
### buildInfo 扩展参数
|
||
|
||
```bash
|
||
# 打印工程级配置
|
||
hvigorw buildInfo
|
||
|
||
# 打印指定模块配置
|
||
hvigorw buildInfo -p module=entry
|
||
|
||
# 包含 buildOption 配置
|
||
hvigorw buildInfo -p buildOption
|
||
|
||
# JSON 格式输出
|
||
hvigorw buildInfo -p json
|
||
```
|
||
|
||
## 其他参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `-h, --help` | 打印帮助信息 |
|
||
| `-v, --version` | 打印版本信息 |
|
||
| `-s, --sync` | 同步工程信息到 `./hvigor/outputs/sync/output.json` |
|
||
| `-m, --mode` | 指定执行目录级别 (如 `-m project`) |
|
||
| `--type-check` | 开启 hvigorfile.ts 类型检查 |
|
||
| `--watch` | 观察模式，用于预览和热加载 |
|
||
| `--node-home <string>` | 指定 Node.js 路径 |
|
||
| `--config, -c` | 指定 hvigor-config.json5 参数 |
|
||
|
||
## CI/CD 常用命令组合
|
||
|
||
```bash
|
||
# 完整的 Release 构建流程
|
||
hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon
|
||
|
||
# 带构建分析的 Debug 构建
|
||
hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon
|
||
|
||
# 运行测试并生成覆盖率报告
|
||
hvigorw onDeviceTest -p coverage=true --no-daemon
|
||
|
||
# 内存受限环境构建
|
||
hvigorw assembleHap --optimization-strategy=memory --no-daemon
|
||
|
||
# 清理缓存
|
||
hvigorw prune
|
||
hvigorw --stop-daemon-all
|
||
```
|