From 81b3c82d168b8a26ed90d25b44dee041ef1260ec Mon Sep 17 00:00:00 2001 From: cheliangzhao Date: Tue, 10 Feb 2026 20:38:13 +0800 Subject: [PATCH] docs: translate reference documentation from Chinese to English - Translate arkguard-obfuscation.md (ArkGuard code obfuscation guide) - Translate hstack.md (stack trace analysis tool) - Translate codelinter.md (code linting tool) - Translate hvigor-commandline.md (Hvigor build tool) - Fix capitalization: ArkTs -> ArkTS in README title --- README.md | 2 +- .../references/arkguard-obfuscation.md | 252 +++++++++--------- arkts-development/references/codelinter.md | 102 +++---- arkts-development/references/hstack.md | 140 +++++----- .../references/hvigor-commandline.md | 206 +++++++------- 5 files changed, 351 insertions(+), 351 deletions(-) diff --git a/README.md b/README.md index 43ca2a3..9dc564b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# AI Skills - HarmonyOS Development +# AI Skills - HarmonyOS/ArkTS Development AI coding agent skills for HarmonyOS/ArkTS application development. diff --git a/arkts-development/references/arkguard-obfuscation.md b/arkts-development/references/arkguard-obfuscation.md index 82cc737..3744f3c 100644 --- a/arkts-development/references/arkguard-obfuscation.md +++ b/arkts-development/references/arkguard-obfuscation.md @@ -1,126 +1,126 @@ -# ArkGuard 代码混淆指南 - -ArkGuard 是 HarmonyOS 官方推荐的代码混淆工具，用于提升应用安全性，防止逆向分析。 - -## 环境要求 - -- **DevEco Studio**: 5.0.3.600 及以上版本 -- **项目模型**: 仅支持 Stage 模型 -- **生效模式**: 仅在 Release 模式下生效 - -## 开启混淆 - -在模块的 `build-profile.json5` 中配置： - -```json -{ - "arkOptions": { - "obfuscation": { - "ruleOptions": { - "enable": true, - "files": ["./obfuscation-rules.txt"] - }, - "consumerFiles": ["./consumer-rules.txt"] - } - } -} -``` - -## 混淆规则配置 - -在项目根目录创建 `obfuscation-rules.txt`： - -```text -# 开启属性混淆 --enable-property-obfuscation - -# 开启顶层作用域名称混淆 --enable-toplevel-obfuscation - -# 开启文件名混淆 --enable-filename-obfuscation - -# 开启导入导出名称混淆 --enable-export-obfuscation -``` - -## 白名单配置 - -某些名称不能混淆（如动态属性名、API 字段、数据库字段等）： - -```text -# 保留属性名 --keep-property-name apiKey --keep-property-name userId --keep-property-name responseData - -# 保留全局名称 --keep-global-name AppConfig - -# 保留文件名 --keep-file-name MainPage --keep-file-name LoginPage -``` - -## 配置文件说明 - -| 配置文件 | 作用 | 可修改 | 影响范围 | -|---------|------|:------:|---------| -| `obfuscation-rules.txt` | 本模块编译时的混淆规则 | ✓ | 本模块 | -| `consumer-rules.txt` | 本模块被依赖时的混淆规则（建议仅配置保留项） | ✓ | 依赖此模块的模块 | -| `obfuscation.txt` | HAR/HSP 构建产物，自动生成 | ✗ | 依赖模块 | - -## 常用混淆选项 - -| 选项 | 说明 | -|------|------| -| `-enable-property-obfuscation` | 混淆对象属性名 | -| `-enable-toplevel-obfuscation` | 混淆顶层作用域的变量和函数名 | -| `-enable-filename-obfuscation` | 混淆文件名 | -| `-enable-export-obfuscation` | 混淆导入导出的名称 | -| `-disable-obfuscation` | 临时禁用混淆（用于调试） | - -## 白名单选项 - -| 选项 | 说明 | -|------|------| -| `-keep-property-name ` | 保留指定属性名不被混淆 | -| `-keep-global-name ` | 保留指定全局名称不被混淆 | -| `-keep-file-name ` | 保留指定文件名不被混淆 | - -## 问题排查 - -### 排查步骤 - -1. **确认是否与混淆相关**: 临时添加 `-disable-obfuscation` 禁用混淆，验证问题是否消失 -2. **定位问题字段**: 根据崩溃日志定位被混淆的关键字段 -3. **添加白名单**: 将问题字段加入 `-keep-property-name` 白名单 - -### 常见需要保留的场景 - -- **网络请求**: 接口传参字段名、响应数据字段名 -- **数据库操作**: 表字段名 -- **系统 API**: 系统回调参数 -- **三方库接口**: 三方库要求的字段名 - -### 示例：网络请求字段保留 - -```text -# API 请求/响应字段 --keep-property-name code --keep-property-name message --keep-property-name data --keep-property-name token --keep-property-name userId -``` - -## 验证混淆效果 - -1. 切换到 **Release** 模式编译 -2. 检查构建产物 -3. 使用反编译工具验证类名/方法名/属性名是否已混淆 -4. 测试应用功能是否正常 - -## 参考 - -- [华为官方文档 - ArkGuard](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-arkguard) +# ArkGuard Code Obfuscation Guide + +ArkGuard is the officially recommended code obfuscation tool for HarmonyOS, designed to enhance application security and prevent reverse engineering. + +## Requirements + +- **DevEco Studio**: Version 5.0.3.600 or above +- **Project Model**: Stage model only +- **Effective Mode**: Only active in Release mode + +## Enabling Obfuscation + +Configure in the module's `build-profile.json5`: + +```json +{ + "arkOptions": { + "obfuscation": { + "ruleOptions": { + "enable": true, + "files": ["./obfuscation-rules.txt"] + }, + "consumerFiles": ["./consumer-rules.txt"] + } + } +} +``` + +## Obfuscation Rules Configuration + +Create `obfuscation-rules.txt` in the project root directory: + +```text +# Enable property obfuscation +-enable-property-obfuscation + +# Enable top-level scope name obfuscation +-enable-toplevel-obfuscation + +# Enable filename obfuscation +-enable-filename-obfuscation + +# Enable import/export name obfuscation +-enable-export-obfuscation +``` + +## Whitelist Configuration + +Certain names must not be obfuscated (e.g., dynamic property names, API fields, database fields): + +```text +# Keep property names +-keep-property-name apiKey +-keep-property-name userId +-keep-property-name responseData + +# Keep global names +-keep-global-name AppConfig + +# Keep file names +-keep-file-name MainPage +-keep-file-name LoginPage +``` + +## Configuration Files + +| Config File | Purpose | Editable | Scope | +|-------------|---------|:--------:|-------| +| `obfuscation-rules.txt` | Obfuscation rules applied when building this module | ✓ | Current module | +| `consumer-rules.txt` | Obfuscation rules applied when this module is used as a dependency (recommended: keep rules only) | ✓ | Modules depending on this module | +| `obfuscation.txt` | HAR/HSP build artifact, auto-generated | ✗ | Dependent modules | + +## Common Obfuscation Options + +| Option | Description | +|--------|-------------| +| `-enable-property-obfuscation` | Obfuscate object property names | +| `-enable-toplevel-obfuscation` | Obfuscate top-level scope variable and function names | +| `-enable-filename-obfuscation` | Obfuscate file names | +| `-enable-export-obfuscation` | Obfuscate import/export names | +| `-disable-obfuscation` | Temporarily disable obfuscation (for debugging) | + +## Whitelist Options + +| Option | Description | +|--------|-------------| +| `-keep-property-name ` | Preserve specified property name from obfuscation | +| `-keep-global-name ` | Preserve specified global name from obfuscation | +| `-keep-file-name ` | Preserve specified file name from obfuscation | + +## Troubleshooting + +### Diagnostic Steps + +1. **Confirm obfuscation is the cause**: Temporarily add `-disable-obfuscation` and check if the issue disappears +2. **Locate the problematic field**: Identify the obfuscated field from crash logs +3. **Add to whitelist**: Add the problematic field to the `-keep-property-name` whitelist + +### Common Scenarios Requiring Whitelisting + +- **Network requests**: Request parameter field names, response data field names +- **Database operations**: Table field names +- **System APIs**: System callback parameters +- **Third-party library interfaces**: Field names required by third-party libraries + +### Example: Preserving Network Request Fields + +```text +# API request/response fields +-keep-property-name code +-keep-property-name message +-keep-property-name data +-keep-property-name token +-keep-property-name userId +``` + +## Verifying Obfuscation Results + +1. Switch to **Release** mode and build +2. Inspect the build artifacts +3. Use decompilation tools to verify that class/method/property names are obfuscated +4. Test that the application functions correctly + +## References + +- [Huawei Official Documentation - ArkGuard](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-arkguard) diff --git a/arkts-development/references/codelinter.md b/arkts-development/references/codelinter.md index 1778daa..61cf881 100644 --- a/arkts-development/references/codelinter.md +++ b/arkts-development/references/codelinter.md @@ -1,103 +1,103 @@ -# CodeLinter 代码检查工具 +# CodeLinter Code Analysis Tool -codelinter 是 HarmonyOS 的代码检查与修复工具，可集成到门禁或 CI/CD 环境中。 +codelinter is a code analysis and auto-fix tool for HarmonyOS, suitable for integration into gating checks or CI/CD pipelines. -## 命令格式 +## Command Format ```bash codelinter [options] [dir] ``` -- `options`: 可选配置参数 -- `dir`: 待检查的工程根目录（可选，默认为当前目录） +- `options`: Optional configuration parameters +- `dir`: Project root directory to check (optional, defaults to current directory) -## 命令参数 +## Command Parameters -| 参数 | 说明 | -|------|------| -| `--config, -c ` | 指定规则配置文件 (code-linter.json5) | -| `--fix` | 检查同时执行自动修复 | -| `--format, -f ` | 输出格式: `default`/`json`/`xml`/`html` | -| `--output, -o ` | 指定结果保存位置（不在命令行显示） | -| `--version, -v` | 查看版本 | -| `--product, -p ` | 指定生效的 product | -| `--incremental, -i` | 仅检查 Git 增量文件（新增/修改/重命名） | -| `--help, -h` | 查询帮助 | -| `--exit-on, -e ` | 指定返回非零退出码的告警级别 | +| Parameter | Description | +|-----------|-------------| +| `--config, -c ` | Specify rule configuration file (code-linter.json5) | +| `--fix` | Check and apply auto-fixes simultaneously | +| `--format, -f ` | Output format: `default`/`json`/`xml`/`html` | +| `--output, -o ` | Specify output file path (suppresses console output) | +| `--version, -v` | Show version | +| `--product, -p ` | Specify the active product | +| `--incremental, -i` | Check only Git incremental files (added/modified/renamed) | +| `--help, -h` | Show help | +| `--exit-on, -e ` | Specify warning levels that trigger a non-zero exit code | -## 基本用法 +## Basic Usage -### 在工程根目录下执行 +### Run in the Project Root Directory ```bash -# 使用默认规则检查当前工程 +# Check current project with default rules codelinter -# 指定规则配置文件 +# Specify a rule configuration file codelinter -c ./code-linter.json5 -# 检查并自动修复 +# Check and apply auto-fixes codelinter -c ./code-linter.json5 --fix ``` -### 在非工程目录下执行 +### Run Outside the Project Directory ```bash -# 检查指定工程目录 +# Check a specific project directory codelinter /path/to/project -# 检查多个目录或文件 +# Check multiple directories or files codelinter dir1 dir2 file1.ets -# 指定规则文件和工程目录 +# Specify rule file and project directory codelinter -c /path/to/code-linter.json5 /path/to/project -# 检查并修复指定工程 +# Check and fix a specific project codelinter -c ./code-linter.json5 /path/to/project --fix ``` -## 输出格式 +## Output Formats ```bash -# 默认文本格式输出到命令行 +# Default text format to console codelinter /path/to/project -# JSON 格式输出 +# JSON format output codelinter /path/to/project -f json -# HTML 格式保存到文件 +# HTML format saved to file codelinter /path/to/project -f html -o ./report.html -# XML 格式保存到文件 +# XML format saved to file codelinter /path/to/project -f xml -o ./report.xml ``` -## 增量检查 +## Incremental Checking -对 Git 工程中的增量文件执行检查（仅检查新增、修改、重命名的文件）： +Check only incremental files in a Git project (only added, modified, or renamed files): ```bash codelinter -i codelinter --incremental ``` -## 指定 Product +## Specifying a Product -当工程存在多个 product 时，指定生效的 product： +When the project has multiple products, specify the active product: ```bash codelinter -p free /path/to/project codelinter --product default ``` -## 退出码 (--exit-on) +## Exit Codes (--exit-on) -用于 CI/CD 中根据告警级别控制流程。告警级别：`error`、`warn`、`suggestion` +Used in CI/CD to control the pipeline based on warning levels. Warning levels: `error`, `warn`, `suggestion` -退出码计算方式（3位二进制数，从高到低表示 error, warn, suggestion）： +Exit code calculation (3-bit binary number, from high to low representing error, warn, suggestion): -| 配置 | 检查结果包含 | 二进制 | 退出码 | -|------|-------------|--------|--------| +| Configuration | Check Results Include | Binary | Exit Code | +|---------------|---------------------|--------|-----------| | `--exit-on error` | error, warn, suggestion | 100 | 4 | | `--exit-on error` | warn, suggestion | 000 | 0 | | `--exit-on error,warn` | error, warn | 110 | 6 | @@ -105,40 +105,40 @@ codelinter --product default | `--exit-on error,warn,suggestion` | error, warn, suggestion | 111 | 7 | ```bash -# 仅 error 级别返回非零退出码 +# Non-zero exit code only for error level codelinter --exit-on error -# error 和 warn 级别返回非零退出码 +# Non-zero exit code for error and warn levels codelinter --exit-on error,warn -# 所有级别都返回非零退出码 +# Non-zero exit code for all levels codelinter --exit-on error,warn,suggestion ``` -## CI/CD 集成示例 +## CI/CD Integration Examples ```bash -# 完整的 CI 检查流程 +# Full CI check pipeline codelinter -c ./code-linter.json5 \ -f json \ -o ./codelinter-report.json \ --exit-on error,warn -# 增量检查（仅检查变更文件） +# Incremental check (changed files only) codelinter -i -c ./code-linter.json5 --exit-on error -# 检查并自动修复，生成 HTML 报告 +# Check with auto-fix, generate HTML report codelinter -c ./code-linter.json5 \ --fix \ -f html \ -o ./codelinter-report.html ``` -## 规则配置文件 (code-linter.json5) +## Rule Configuration File (code-linter.json5) -默认规则清单可在检查完成后，根据命令行提示查看生成的 `code-linter.json5` 文件。 +The default rule list can be viewed in the generated `code-linter.json5` file, as indicated by the console output after a check completes. -示例配置： +Example configuration: ```json5 { diff --git a/arkts-development/references/hstack.md b/arkts-development/references/hstack.md index 96678bb..1aeabee 100644 --- a/arkts-development/references/hstack.md +++ b/arkts-development/references/hstack.md @@ -1,92 +1,92 @@ -# 堆栈解析工具 (hstack) +# Stack Trace Analysis Tool (hstack) -hstack 是用于将 Release 应用混淆后的 crash 堆栈解析为源码对应堆栈的工具，支持 Windows、Mac、Linux 三个平台。 +hstack is a tool for resolving obfuscated crash stack traces from Release builds back to their original source code locations. It supports Windows, Mac, and Linux. -## 命令格式 +## Command Format ```bash hstack [options] ``` -## 命令参数 +## Command Parameters -| 参数 | 说明 | -|------|------| -| `-i, --input` | 指定 crash 文件归档目录 | -| `-c, --crash` | 指定一条 crash 堆栈 | -| `-o, --output` | 指定解析结果输出目录（使用 `-c` 时指定输出文件） | -| `-s, --sourcemapDir` | 指定 sourcemap 文件归档目录 | -| `--so, --soDir` | 指定 shared object (.so) 文件归档目录 | -| `-n, --nameObfuscation` | 指定 nameCache 文件归档目录 | -| `-v, --version` | 查看版本 | -| `-h, --help` | 查询帮助 | +| Parameter | Description | +|-----------|-------------| +| `-i, --input` | Specify the crash file archive directory | +| `-c, --crash` | Specify a single crash stack trace | +| `-o, --output` | Specify the output directory for parsed results (output file when using `-c`) | +| `-s, --sourcemapDir` | Specify the sourcemap file archive directory | +| `--so, --soDir` | Specify the shared object (.so) file archive directory | +| `-n, --nameObfuscation` | Specify the nameCache file archive directory | +| `-v, --version` | Show version | +| `-h, --help` | Show help | -## 参数约束 +## Parameter Constraints -- crash 文件目录 (`-i`) 与 crash 堆栈 (`-c`) **必须且只能提供一项** -- sourcemap (`-s`) 与 shared object (`--so`) 目录**至少提供一项** -- 如需还原混淆的方法名，需**同时提供** sourcemap 和 nameCache 文件 -- 路径参数不支持特殊字符：`` `~!@#$^&*=|{};,\s\[\]<>? `` +- Crash file directory (`-i`) and crash stack trace (`-c`) **must provide exactly one** +- Sourcemap (`-s`) and shared object (`--so`) directories **must provide at least one** +- To restore obfuscated method names, **both** sourcemap and nameCache files must be provided +- Path parameters do not support special characters: `` `~!@#$^&*=|{};,\s\[\]<>? `` -## 环境配置 +## Environment Setup -1. 将 Command Line Tools 的 `bin` 目录配置到 PATH 环境变量 -2. 配置 Node.js 到环境变量 -3. 解析 C++ 异常需配置 SDK 的 `native\llvm\bin` 目录到环境变量 `ADDR2LINE_PATH` +1. Add the Command Line Tools `bin` directory to the PATH environment variable +2. Add Node.js to the environment variables +3. To parse C++ exceptions, add the SDK's `native\llvm\bin` directory to the `ADDR2LINE_PATH` environment variable -## 使用示例 +## Usage Examples -### 解析 crash 文件目录 +### Parse Crash File Directory ```bash -# 完整解析命令 +# Full parse command hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir -# 仅使用 sourcemap 解析 (ArkTS) +# Parse using sourcemap only (ArkTS) hstack -i crashDir -o outputDir -s sourcemapDir -# 仅使用 so 文件解析 (C++) +# Parse using .so files only (C++) hstack -i crashDir -o outputDir --so soDir -# 包含方法名还原 +# Include method name restoration hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir ``` -### 解析单条堆栈 +### Parse a Single Stack Trace ```bash -# 输出到控制台 +# Output to console hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -# 输出到文件 +# Output to file hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir -o result.txt ``` -## 输出说明 +## Output -- 解析结果输出到 `-o` 指定目录，文件以原始 crash 文件名加 `_` 前缀命名 -- 不指定 `-o` 时： - - 使用 `-i` 输入：输出到 crashDir 目录 - - 使用 `-c` 输入：直接输出到控制台 +- Parsed results are written to the directory specified by `-o`, with filenames prefixed by `_` followed by the original crash filename +- When `-o` is not specified: + - With `-i` input: output to the crashDir directory + - With `-c` input: output directly to console -## 文件获取 +## File Sources -### Sourcemap 文件 +### Sourcemap Files -构建产物中的 sourcemap 文件，包含： -- 路径信息映射 -- 行列号映射 (mappings 字段) -- package-info 信息 +Sourcemap files from build artifacts, containing: +- Path information mapping +- Line/column number mapping (mappings field) +- package-info information -### NameCache 文件 +### NameCache Files -构建产物中的 nameCache 文件，包含： -- `IdentifierCache`: 标识符混淆映射 -- `MemberMethodCache`: 成员方法混淆映射，格式为 `"源码方法名:起始行:结束行": "混淆后方法名"` +NameCache files from build artifacts, containing: +- `IdentifierCache`: Identifier obfuscation mapping +- `MemberMethodCache`: Member method obfuscation mapping, format: `"sourceMethodName:startLine:endLine": "obfuscatedMethodName"` -### Shared Object (.so) 文件 +### Shared Object (.so) Files -构建 Release 应用时，默认 so 文件不包含符号表。如需生成包含符号表的 so 文件，在模块 `build-profile.json5` 中配置： +When building Release applications, .so files do not include symbol tables by default. To generate .so files with symbol tables, configure in the module's `build-profile.json5`: ```json5 { @@ -98,46 +98,46 @@ hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s source } ``` -## 堆栈解析原理 +## Stack Trace Resolution Principles -### Crash 堆栈格式 +### Crash Stack Format ``` at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58) at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71) ``` -路径格式：`引用方packageName|被引用方packageName|version|源码相对路径` +Path format: `referrerPackageName|referredPackageName|version|sourceRelativePath` -### 解析步骤 +### Resolution Steps -1. **根据路径信息找到 sourcemap** - - 从路径 `entry|har|1.0.0|src/main/ets/...` 在 entry 模块 sourcemap 中查找对应字段 +1. **Find the sourcemap based on path information** + - From the path `entry|har|1.0.0|src/main/ets/...`, look up the corresponding field in the entry module's sourcemap -2. **利用 sourcemap 还原路径和行列号** - - 根据 `sources` 和 `mappings` 字段解析 - - 如包含 `package-info`，可进行二次解析获取更准确的源码位置 +2. **Restore path and line/column numbers using sourcemap** + - Parse using the `sources` and `mappings` fields + - If `package-info` is included, perform a secondary parse for more accurate source locations -3. **利用 nameCache 还原方法名** - - 查找混淆后方法名对应的所有条目 - - 根据还原后的行号范围匹配正确的源码方法名 +3. **Restore method names using nameCache** + - Find all entries matching the obfuscated method name + - Match the correct source method name based on the restored line number range -### 解析示例 +### Resolution Example -原始堆栈： +Original stack trace: ``` at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71) ``` -还原后： +After resolution: ``` at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3) ``` -## CI/CD 集成 +## CI/CD Integration ```bash -# 自动化解析脚本示例 +# Automated parsing script example hstack \ -i ./crash-logs \ -o ./parsed-logs \ @@ -146,8 +146,8 @@ hstack \ -n ./build/nameCache ``` -## 常见问题 +## FAQ -1. **方法名未还原**: 确保同时提供 `-s` 和 `-n` 参数 -2. **C++ 堆栈未解析**: 检查 `ADDR2LINE_PATH` 环境变量配置 -3. **so 文件无符号表**: 配置 `RelWithDebInfo` 构建选项 +1. **Method names not restored**: Ensure both `-s` and `-n` parameters are provided +2. **C++ stack traces not parsed**: Check the `ADDR2LINE_PATH` environment variable configuration +3. **No symbol table in .so files**: Configure the `RelWithDebInfo` build option diff --git a/arkts-development/references/hvigor-commandline.md b/arkts-development/references/hvigor-commandline.md index 76e99e6..24a9f40 100644 --- a/arkts-development/references/hvigor-commandline.md +++ b/arkts-development/references/hvigor-commandline.md @@ -1,179 +1,179 @@ -# Hvigor 命令行构建工具 (hvigorw) +# Hvigor Command-Line Build Tool (hvigorw) -hvigorw 是 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。 +hvigorw is the Hvigor wrapper tool that supports automatic installation of the Hvigor build tool and its plugin dependencies, as well as executing Hvigor build commands. -## 命令格式 +## Command Format ```bash hvigorw [taskNames...] ``` -## 编译构建任务 +## Build Tasks -| 任务 | 说明 | -|------|------| -| `clean` | 清理构建产物 build 目录 | -| `assembleHap` | 构建 Hap 应用 | -| `assembleApp` | 构建 App 应用 | -| `assembleHsp` | 构建 Hsp 包 | -| `assembleHar` | 构建 Har 包 | -| `collectCoverage` | 基于打点数据生成覆盖率统计报表 | +| Task | Description | +|------|-------------| +| `clean` | Clean build artifacts in the build directory | +| `assembleHap` | Build HAP application | +| `assembleApp` | Build APP application | +| `assembleHsp` | Build HSP package | +| `assembleHar` | Build HAR package | +| `collectCoverage` | Generate coverage statistics report from instrumented data | -## 常用构建参数 +## Common Build Parameters -| 参数 | 说明 | -|------|------| -| `-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 的参数配置文件 | +| Parameter | Description | +|-----------|-------------| +| `-p buildMode={debug\|release}` | Specify build mode. Default: debug for Hap/Hsp/Har, release for App | +| `-p debuggable=true/false` | Override the debuggable setting in buildOption | +| `-p product={ProductName}` | Specify product for compilation, defaults to default | +| `-p module={ModuleName}@{TargetName}` | Specify module and target for compilation (requires `--mode module`) | +| `-p ohos-test-coverage={true\|false}` | Enable test framework code coverage instrumentation | +| `-p parameterFile=param.json` | Set parameter configuration file for oh-package.json5 | -## 构建示例 +## Build Examples ```bash -# 清理构建产物 +# Clean build artifacts hvigorw clean -# Debug 模式构建 Hap +# Build HAP in debug mode hvigorw assembleHap -p buildMode=debug -# Release 模式构建 App +# Build APP in release mode hvigorw assembleApp -p buildMode=release -# 构建指定 product +# Build a specific product hvigorw assembleHap -p product=free -# 构建指定模块 +# Build a specific module hvigorw assembleHap -p module=entry@default --mode module -# 构建多个模块 +# Build multiple modules hvigorw assembleHar -p module=library1@default,library2@default --mode module ``` -## 测试命令 +## Test Commands -### Instrument Test (设备测试) +### Instrument Test (On-Device 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`: Module to test; omit to test all modules +- `coverage`: Whether to generate coverage report, defaults to true +- `scope`: Test scope, format `{suiteName}#{methodName}` or `{suiteName}` +- `ohos-debug-asan`: Whether to enable ASan detection, defaults to false (5.19.0+) -**输出路径:** -- 覆盖率报告: `/.test/default/outputs/ohosTest/reports` -- 测试结果: `//.test/default/intermediates/ohosTest/coverage_data/test_result.txt` +**Output paths:** +- Coverage report: `/.test/default/outputs/ohosTest/reports` +- Test results: `//.test/default/intermediates/ohosTest/coverage_data/test_result.txt` -### Local Test (本地测试) +### Local Test ```bash hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName} ``` -**输出路径:** -- 覆盖率报告: `/.test/default/outputs/test/reports` -- 测试结果: `//.test/default/intermediates/test/coverage_data/test_result.txt` +**Output paths:** +- Coverage report: `/.test/default/outputs/test/reports` +- Test results: `//.test/default/intermediates/test/coverage_data/test_result.txt` -## 日志级别 +## Log Levels -| 参数 | 说明 | -|------|------| -| `-e, --error` | 设置日志级别为 error | -| `-w, --warn` | 设置日志级别为 warn | -| `-i, --info` | 设置日志级别为 info | -| `-d, --debug` | 设置日志级别为 debug | -| `--stacktrace` | 开启打印异常堆栈信息 | +| Parameter | Description | +|-----------|-------------| +| `-e, --error` | Set log level to error | +| `-w, --warn` | Set log level to warn | +| `-i, --info` | Set log level to info | +| `-d, --debug` | Set log level to debug | +| `--stacktrace` | Enable exception stack trace printing | -## 构建分析 (Build Analyzer) +## Build Analyzer -| 参数 | 说明 | -|------|------| -| `--analyze=normal` | 普通模式分析 | -| `--analyze=advanced` | 进阶模式，更详细的任务耗时数据 | -| `--analyze=ultrafine` | 超精细化模式，ArkTS 编译详细打点 (6.0.0+) | -| `--analyze=false` | 不启用构建分析 | -| `--config properties.hvigor.analyzeHtml=true` | 生成 HTML 可视化报告到 `.hvigor/report` | +| Parameter | Description | +|-----------|-------------| +| `--analyze=normal` | Normal mode analysis | +| `--analyze=advanced` | Advanced mode with detailed task timing data | +| `--analyze=ultrafine` | Ultra-fine mode with detailed ArkTS compilation instrumentation (6.0.0+) | +| `--analyze=false` | Disable build analysis | +| `--config properties.hvigor.analyzeHtml=true` | Generate HTML visual report to `.hvigor/report` | -## 守护进程 (Daemon) +## 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+) | +| Parameter | Description | +|-----------|-------------| +| `--daemon` | Enable daemon process | +| `--no-daemon` | Disable daemon process (recommended for CLI mode) | +| `--stop-daemon` | Stop the daemon for the current project | +| `--stop-daemon-all` | Stop all project daemons | +| `--status-daemon` | Query all Hvigor daemon process information | +| `--max-old-space-size=12345` | Set old generation memory size (MB) | +| `--max-semi-space-size=32` | Set new generation semi-space size (MB, 5.18.4+) | -## 性能与内存优化 +## Performance and Memory Optimization -| 参数 | 说明 | -|------|------| -| `--parallel` / `--no-parallel` | 开启/关闭并行构建（默认开启） | -| `--incremental` / `--no-incremental` | 开启/关闭增量构建（默认开启） | -| `--optimization-strategy=performance` | 性能优先模式，加快构建但占用更多内存 (5.19.2+) | -| `--optimization-strategy=memory` | 内存优先模式（默认）(5.19.2+) | +| Parameter | Description | +|-----------|-------------| +| `--parallel` / `--no-parallel` | Enable/disable parallel builds (enabled by default) | +| `--incremental` / `--no-incremental` | Enable/disable incremental builds (enabled by default) | +| `--optimization-strategy=performance` | Performance-first mode, faster builds but higher memory usage (5.19.2+) | +| `--optimization-strategy=memory` | Memory-first mode (default) (5.19.2+) | -## 公共命令 +## Utility Commands -| 任务 | 说明 | -|------|------| -| `tasks` | 打印工程各模块包含的任务信息 | -| `taskTree` | 打印工程各模块的任务依赖关系 | -| `prune` | 清除 30 天未使用的缓存并删除 pnpm 未引用包 | -| `buildInfo` | 打印 build-profile.json5 配置信息 (5.18.4+) | +| Task | Description | +|------|-------------| +| `tasks` | Print task information for all project modules | +| `taskTree` | Print task dependency graph for all project modules | +| `prune` | Clean caches unused for 30 days and remove unreferenced pnpm packages | +| `buildInfo` | Print build-profile.json5 configuration information (5.18.4+) | -### buildInfo 扩展参数 +### buildInfo Extended Parameters ```bash -# 打印工程级配置 +# Print project-level configuration hvigorw buildInfo -# 打印指定模块配置 +# Print configuration for a specific module hvigorw buildInfo -p module=entry -# 包含 buildOption 配置 +# Include buildOption configuration hvigorw buildInfo -p buildOption -# JSON 格式输出 +# JSON format output hvigorw buildInfo -p json ``` -## 其他参数 +## Other Parameters -| 参数 | 说明 | -|------|------| -| `-h, --help` | 打印帮助信息 | -| `-v, --version` | 打印版本信息 | -| `-s, --sync` | 同步工程信息到 `./hvigor/outputs/sync/output.json` | -| `-m, --mode` | 指定执行目录级别 (如 `-m project`) | -| `--type-check` | 开启 hvigorfile.ts 类型检查 | -| `--watch` | 观察模式，用于预览和热加载 | -| `--node-home ` | 指定 Node.js 路径 | -| `--config, -c` | 指定 hvigor-config.json5 参数 | +| Parameter | Description | +|-----------|-------------| +| `-h, --help` | Print help information | +| `-v, --version` | Print version information | +| `-s, --sync` | Sync project information to `./hvigor/outputs/sync/output.json` | +| `-m, --mode` | Specify execution directory level (e.g., `-m project`) | +| `--type-check` | Enable type checking for hvigorfile.ts | +| `--watch` | Watch mode for preview and hot reload | +| `--node-home ` | Specify Node.js path | +| `--config, -c` | Specify hvigor-config.json5 parameters | -## CI/CD 常用命令组合 +## CI/CD Common Command Combinations ```bash -# 完整的 Release 构建流程 +# Full release build pipeline hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon -# 带构建分析的 Debug 构建 +# Debug build with build analysis hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon -# 运行测试并生成覆盖率报告 +# Run tests and generate coverage report hvigorw onDeviceTest -p coverage=true --no-daemon -# 内存受限环境构建 +# Build in memory-constrained environment hvigorw assembleHap --optimization-strategy=memory --no-daemon -# 清理缓存 +# Clean caches hvigorw prune hvigorw --stop-daemon-all ```