arkts-skills/arkts-development/references/hvigor-commandline.md

Hvigor 命令行构建工具 (hvigorw)

hvigorw 是 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。

命令格式

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 的参数配置文件

构建示例

# 清理构建产物
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 (设备测试)

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 (本地测试)

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 扩展参数

# 打印工程级配置
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 常用命令组合

# 完整的 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