clz/arkts-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: translate reference documentation from Chinese to English

Browse Source 
- 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
This commit is contained in:
cheliangzhao
2026-02-10 20:38:13 +08:00
parent a68f3d1a7d
commit 81b3c82d16
5 changed files with 351 additions and 351 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -1,4 +1,4 @@
# AI Skills - HarmonyOS Development # AI Skills - HarmonyOS/ArkTS Development
AI coding agent skills for HarmonyOS/ArkTS application development. AI coding agent skills for HarmonyOS/ArkTS application development.

116
arkts-development/references/arkguard-obfuscation.md
View File

@@ -1,16 +1,16 @@
# ArkGuard 代码混淆指南 # ArkGuard Code Obfuscation Guide
ArkGuard 是 HarmonyOS 官方推荐的代码混淆工具，用于提升应用安全性，防止逆向分析。 ArkGuard is the officially recommended code obfuscation tool for HarmonyOS, designed to enhance application security and prevent reverse engineering.
## 环境要求 ## Requirements
- **DevEco Studio**: 5.0.3.600 及以上版本 - **DevEco Studio**: Version 5.0.3.600 or above
- **项目模型**: 仅支持 Stage 模型 - **Project Model**: Stage model only
- **生效模式**: 仅在 Release 模式下生效 - **Effective Mode**: Only active in Release mode
## 开启混淆 ## Enabling Obfuscation
在模块的 `build-profile.json5` 中配置： Configure in the module's `build-profile.json5`:
```json ```json
{ {
@@ -26,87 +26,87 @@ ArkGuard 是 HarmonyOS 官方推荐的代码混淆工具，用于提升应用安
} }
``` ```
## 混淆规则配置 ## Obfuscation Rules Configuration
在项目根目录创建 `obfuscation-rules.txt`： Create `obfuscation-rules.txt` in the project root directory:
```text ```text
# 开启属性混淆 # Enable property obfuscation
-enable-property-obfuscation -enable-property-obfuscation
# 开启顶层作用域名称混淆 # Enable top-level scope name obfuscation
-enable-toplevel-obfuscation -enable-toplevel-obfuscation
# 开启文件名混淆 # Enable filename obfuscation
-enable-filename-obfuscation -enable-filename-obfuscation
# 开启导入导出名称混淆 # Enable import/export name obfuscation
-enable-export-obfuscation -enable-export-obfuscation
``` ```
## 白名单配置 ## Whitelist Configuration
某些名称不能混淆（如动态属性名、API 字段、数据库字段等）： Certain names must not be obfuscated (e.g., dynamic property names, API fields, database fields):
```text ```text
# 保留属性名 # Keep property names
-keep-property-name apiKey -keep-property-name apiKey
-keep-property-name userId -keep-property-name userId
-keep-property-name responseData -keep-property-name responseData
# 保留全局名称 # Keep global names
-keep-global-name AppConfig -keep-global-name AppConfig
# 保留文件名 # Keep file names
-keep-file-name MainPage -keep-file-name MainPage
-keep-file-name LoginPage -keep-file-name LoginPage
``` ```
## 配置文件说明 ## Configuration Files
| 配置文件 | 作用 | 可修改 | 影响范围 | | Config File | Purpose | Editable | Scope |
|---------|------|:------:|---------| |-------------|---------|:--------:|-------|
| `obfuscation-rules.txt` | 本模块编译时的混淆规则 | ✓ | 本模块 | | `obfuscation-rules.txt` | Obfuscation rules applied when building this module | ✓ | Current module |
| `consumer-rules.txt` | 本模块被依赖时的混淆规则（建议仅配置保留项） | ✓ | 依赖此模块的模块 | | `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 构建产物，自动生成 | ✗ | 依赖模块 | | `obfuscation.txt` | HAR/HSP build artifact, auto-generated | ✗ | Dependent modules |
## 常用混淆选项 ## Common Obfuscation Options
| 选项 | 说明 | | Option | Description |
|------|------| |--------|-------------|
| `-enable-property-obfuscation` | 混淆对象属性名 | | `-enable-property-obfuscation` | Obfuscate object property names |
| `-enable-toplevel-obfuscation` | 混淆顶层作用域的变量和函数名 | | `-enable-toplevel-obfuscation` | Obfuscate top-level scope variable and function names |
| `-enable-filename-obfuscation` | 混淆文件名 | | `-enable-filename-obfuscation` | Obfuscate file names |
| `-enable-export-obfuscation` | 混淆导入导出的名称 | | `-enable-export-obfuscation` | Obfuscate import/export names |
| `-disable-obfuscation` | 临时禁用混淆（用于调试） | | `-disable-obfuscation` | Temporarily disable obfuscation (for debugging) |
## 白名单选项 ## Whitelist Options
| 选项 | 说明 | | Option | Description |
|------|------| |--------|-------------|
| `-keep-property-name <name>` | 保留指定属性名不被混淆 | | `-keep-property-name <name>` | Preserve specified property name from obfuscation |
| `-keep-global-name <name>` | 保留指定全局名称不被混淆 | | `-keep-global-name <name>` | Preserve specified global name from obfuscation |
| `-keep-file-name <name>` | 保留指定文件名不被混淆 | | `-keep-file-name <name>` | Preserve specified file name from obfuscation |
## 问题排查 ## Troubleshooting
### 排查步骤 ### Diagnostic Steps
1. **确认是否与混淆相关**: 临时添加 `-disable-obfuscation` 禁用混淆，验证问题是否消失 1. **Confirm obfuscation is the cause**: Temporarily add `-disable-obfuscation` and check if the issue disappears
2. **定位问题字段**: 根据崩溃日志定位被混淆的关键字段 2. **Locate the problematic field**: Identify the obfuscated field from crash logs
3. **添加白名单**: 将问题字段加入 `-keep-property-name` 白名单 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
- **系统 API**: 系统回调参数 - **System APIs**: System callback parameters
- **三方库接口**: 三方库要求的字段名 - **Third-party library interfaces**: Field names required by third-party libraries
### 示例：网络请求字段保留 ### Example: Preserving Network Request Fields
```text ```text
# API 请求/响应字段 # API request/response fields
-keep-property-name code -keep-property-name code
-keep-property-name message -keep-property-name message
-keep-property-name data -keep-property-name data
@@ -114,13 +114,13 @@ ArkGuard 是 HarmonyOS 官方推荐的代码混淆工具，用于提升应用安
-keep-property-name userId -keep-property-name userId
``` ```
## 验证混淆效果 ## Verifying Obfuscation Results
1. 切换到 **Release** 模式编译 1. Switch to **Release** mode and build
2. 检查构建产物 2. Inspect the build artifacts
3. 使用反编译工具验证类名/方法名/属性名是否已混淆 3. Use decompilation tools to verify that class/method/property names are obfuscated
4. 测试应用功能是否正常 4. Test that the application functions correctly
## 参考 ## References
- [华为官方文档 - ArkGuard](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-arkguard) - [Huawei Official Documentation - ArkGuard](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-arkguard)

102
arkts-development/references/codelinter.md
View File

@@ -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 ```bash
codelinter [options] [dir] codelinter [options] [dir]
``` ```
- `options`: 可选配置参数 - `options`: Optional configuration parameters
- `dir`: 待检查的工程根目录（可选，默认为当前目录） - `dir`: Project root directory to check (optional, defaults to current directory)
## 命令参数 ## Command Parameters
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `--config, -c <filepath>` | 指定规则配置文件 (code-linter.json5) | | `--config, -c <filepath>` | Specify rule configuration file (code-linter.json5) |
| `--fix` | 检查同时执行自动修复 | | `--fix` | Check and apply auto-fixes simultaneously |
| `--format, -f <format>` | 输出格式: `default`/`json`/`xml`/`html` | | `--format, -f <format>` | Output format: `default`/`json`/`xml`/`html` |
| `--output, -o <filepath>` | 指定结果保存位置（不在命令行显示） | | `--output, -o <filepath>` | Specify output file path (suppresses console output) |
| `--version, -v` | 查看版本 | | `--version, -v` | Show version |
| `--product, -p <productName>` | 指定生效的 product | | `--product, -p <productName>` | Specify the active product |
| `--incremental, -i` | 仅检查 Git 增量文件（新增/修改/重命名） | | `--incremental, -i` | Check only Git incremental files (added/modified/renamed) |
| `--help, -h` | 查询帮助 | | `--help, -h` | Show help |
| `--exit-on, -e <levels>` | 指定返回非零退出码的告警级别 | | `--exit-on, -e <levels>` | Specify warning levels that trigger a non-zero exit code |
## 基本用法 ## Basic Usage
### 在工程根目录下执行 ### Run in the Project Root Directory
```bash ```bash
# 使用默认规则检查当前工程 # Check current project with default rules
codelinter codelinter
# 指定规则配置文件 # Specify a rule configuration file
codelinter -c ./code-linter.json5 codelinter -c ./code-linter.json5
# 检查并自动修复 # Check and apply auto-fixes
codelinter -c ./code-linter.json5 --fix codelinter -c ./code-linter.json5 --fix
``` ```
### 在非工程目录下执行 ### Run Outside the Project Directory
```bash ```bash
# 检查指定工程目录 # Check a specific project directory
codelinter /path/to/project codelinter /path/to/project
# 检查多个目录或文件 # Check multiple directories or files
codelinter dir1 dir2 file1.ets codelinter dir1 dir2 file1.ets
# 指定规则文件和工程目录 # Specify rule file and project directory
codelinter -c /path/to/code-linter.json5 /path/to/project 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 codelinter -c ./code-linter.json5 /path/to/project --fix
``` ```
## 输出格式 ## Output Formats
```bash ```bash
# 默认文本格式输出到命令行 # Default text format to console
codelinter /path/to/project codelinter /path/to/project
# JSON 格式输出 # JSON format output
codelinter /path/to/project -f json codelinter /path/to/project -f json
# HTML 格式保存到文件 # HTML format saved to file
codelinter /path/to/project -f html -o ./report.html codelinter /path/to/project -f html -o ./report.html
# XML 格式保存到文件 # XML format saved to file
codelinter /path/to/project -f xml -o ./report.xml 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 ```bash
codelinter -i codelinter -i
codelinter --incremental codelinter --incremental
``` ```
## 指定 Product ## Specifying a Product
当工程存在多个 product 时，指定生效的 product： When the project has multiple products, specify the active product:
```bash ```bash
codelinter -p free /path/to/project codelinter -p free /path/to/project
codelinter --product default 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` | error, warn, suggestion | 100 | 4 |
| `--exit-on error` | warn, suggestion | 000 | 0 | | `--exit-on error` | warn, suggestion | 000 | 0 |
| `--exit-on error,warn` | error, warn | 110 | 6 | | `--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 | | `--exit-on error,warn,suggestion` | error, warn, suggestion | 111 | 7 |
```bash ```bash
# 仅 error 级别返回非零退出码 # Non-zero exit code only for error level
codelinter --exit-on error codelinter --exit-on error
# error 和 warn 级别返回非零退出码 # Non-zero exit code for error and warn levels
codelinter --exit-on error,warn codelinter --exit-on error,warn
# 所有级别都返回非零退出码 # Non-zero exit code for all levels
codelinter --exit-on error,warn,suggestion codelinter --exit-on error,warn,suggestion
``` ```
## CI/CD 集成示例 ## CI/CD Integration Examples
```bash ```bash
# 完整的 CI 检查流程 # Full CI check pipeline
codelinter -c ./code-linter.json5 \ codelinter -c ./code-linter.json5 \
-f json \ -f json \
-o ./codelinter-report.json \ -o ./codelinter-report.json \
--exit-on error,warn --exit-on error,warn
# 增量检查（仅检查变更文件） # Incremental check (changed files only)
codelinter -i -c ./code-linter.json5 --exit-on error codelinter -i -c ./code-linter.json5 --exit-on error
# 检查并自动修复，生成 HTML 报告 # Check with auto-fix, generate HTML report
codelinter -c ./code-linter.json5 \ codelinter -c ./code-linter.json5 \
--fix \ --fix \
-f html \ -f html \
-o ./codelinter-report.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 ```json5
{ {

140
arkts-development/references/hstack.md
View File

@@ -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 ```bash
hstack [options] hstack [options]
``` ```
## 命令参数 ## Command Parameters
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `-i, --input` | 指定 crash 文件归档目录 | | `-i, --input` | Specify the crash file archive directory |
| `-c, --crash` | 指定一条 crash 堆栈 | | `-c, --crash` | Specify a single crash stack trace |
| `-o, --output` | 指定解析结果输出目录（使用 `-c` 时指定输出文件） | | `-o, --output` | Specify the output directory for parsed results (output file when using `-c`) |
| `-s, --sourcemapDir` | 指定 sourcemap 文件归档目录 | | `-s, --sourcemapDir` | Specify the sourcemap file archive directory |
| `--so, --soDir` | 指定 shared object (.so) 文件归档目录 | | `--so, --soDir` | Specify the shared object (.so) file archive directory |
| `-n, --nameObfuscation` | 指定 nameCache 文件归档目录 | | `-n, --nameObfuscation` | Specify the nameCache file archive directory |
| `-v, --version` | 查看版本 | | `-v, --version` | Show version |
| `-h, --help` | 查询帮助 | | `-h, --help` | Show help |
## 参数约束 ## Parameter Constraints
- crash 文件目录 (`-i`) 与 crash 堆栈 (`-c`) **必须且只能提供一项** - Crash file directory (`-i`) and crash stack trace (`-c`) **must provide exactly one**
- sourcemap (`-s`) 与 shared object (`--so`) 目录**至少提供一项** - Sourcemap (`-s`) and shared object (`--so`) directories **must provide at least one**
- 如需还原混淆的方法名，需**同时提供** sourcemap 和 nameCache 文件 - To restore obfuscated method names, **both** sourcemap and nameCache files must be provided
- 路径参数不支持特殊字符：`` `~!@#$^&*=|{};,\s\[\]<>? `` - Path parameters do not support special characters: `` `~!@#$^&*=|{};,\s\[\]<>? ``
## 环境配置 ## Environment Setup
1. 将 Command Line Tools 的 `bin` 目录配置到 PATH 环境变量 1. Add the Command Line Tools `bin` directory to the PATH environment variable
2. 配置 Node.js 到环境变量 2. Add Node.js to the environment variables
3. 解析 C++ 异常需配置 SDK 的 `native\llvm\bin` 目录到环境变量 `ADDR2LINE_PATH` 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 ```bash
# 完整解析命令 # Full parse command
hstack -i crashDir -o outputDir -s sourcemapDir --so soDir -n nameCacheDir 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 hstack -i crashDir -o outputDir -s sourcemapDir
# 仅使用 so 文件解析 (C++) # Parse using .so files only (C++)
hstack -i crashDir -o outputDir --so soDir hstack -i crashDir -o outputDir --so soDir
# 包含方法名还原 # Include method name restoration
hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir hstack -i crashDir -o outputDir -s sourcemapDir -n nameCacheDir
``` ```
### 解析单条堆栈 ### Parse a Single Stack Trace
```bash ```bash
# 输出到控制台 # Output to console
hstack -c "at har (entry|har|1.0.0|src/main/ets/pages/Index.ts:58:58)" -s sourcemapDir 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 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 文件名加 `_` 前缀命名 - Parsed results are written to the directory specified by `-o`, with filenames prefixed by `_` followed by the original crash filename
- 不指定 `-o` 时： - When `-o` is not specified:
- 使用 `-i` 输入：输出到 crashDir 目录 - With `-i` input: output to the crashDir directory
- 使用 `-c` 输入：直接输出到控制台 - With `-c` input: output directly to console
## 文件获取 ## File Sources
### Sourcemap 文件 ### Sourcemap Files
构建产物中的 sourcemap 文件，包含： Sourcemap files from build artifacts, containing:
- 路径信息映射 - Path information mapping
- 行列号映射 (mappings 字段) - Line/column number mapping (mappings field)
- package-info 信息 - package-info information
### NameCache 文件 ### NameCache Files
构建产物中的 nameCache 文件，包含： NameCache files from build artifacts, containing:
- `IdentifierCache`: 标识符混淆映射 - `IdentifierCache`: Identifier obfuscation mapping
- `MemberMethodCache`: 成员方法混淆映射，格式为 `"源码方法名:起始行:结束行": "混淆后方法名"` - `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 ```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 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) 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** 1. **Find the sourcemap based on path information**
- 从路径 `entry|har|1.0.0|src/main/ets/...` 在 entry 模块 sourcemap 中查找对应字段 - From the path `entry|har|1.0.0|src/main/ets/...`, look up the corresponding field in the entry module's sourcemap
2. **利用 sourcemap 还原路径和行列号** 2. **Restore path and line/column numbers using sourcemap**
- 根据 `sources` 和 `mappings` 字段解析 - Parse using the `sources` and `mappings` fields
- 如包含 `package-info`，可进行二次解析获取更准确的源码位置 - 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) 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) at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3)
``` ```
## CI/CD 集成 ## CI/CD Integration
```bash ```bash
# 自动化解析脚本示例 # Automated parsing script example
hstack \ hstack \
-i ./crash-logs \ -i ./crash-logs \
-o ./parsed-logs \ -o ./parsed-logs \
@@ -146,8 +146,8 @@ hstack \
-n ./build/nameCache -n ./build/nameCache
``` ```
## 常见问题 ## FAQ
1. **方法名未还原**: 确保同时提供 `-s` 和 `-n` 参数 1. **Method names not restored**: Ensure both `-s` and `-n` parameters are provided
2. **C++ 堆栈未解析**: 检查 `ADDR2LINE_PATH` 环境变量配置 2. **C++ stack traces not parsed**: Check the `ADDR2LINE_PATH` environment variable configuration
3. **so 文件无符号表**: 配置 `RelWithDebInfo` 构建选项 3. **No symbol table in .so files**: Configure the `RelWithDebInfo` build option

206
arkts-development/references/hvigor-commandline.md
View File

@@ -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 ```bash
hvigorw [taskNames...] <options> hvigorw [taskNames...] <options>
``` ```
## 编译构建任务 ## Build Tasks
| 任务 | 说明 | | Task | Description |
|------|------| |------|-------------|
| `clean` | 清理构建产物 build 目录 | | `clean` | Clean build artifacts in the build directory |
| `assembleHap` | 构建 Hap 应用 | | `assembleHap` | Build HAP application |
| `assembleApp` | 构建 App 应用 | | `assembleApp` | Build APP application |
| `assembleHsp` | 构建 Hsp 包 | | `assembleHsp` | Build HSP package |
| `assembleHar` | 构建 Har 包 | | `assembleHar` | Build HAR package |
| `collectCoverage` | 基于打点数据生成覆盖率统计报表 | | `collectCoverage` | Generate coverage statistics report from instrumented data |
## 常用构建参数 ## Common Build Parameters
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `-p buildMode={debug\|release}` | 指定构建模式。默认：Hap/Hsp/Har 为 debug，App 为 release | | `-p buildMode={debug\|release}` | Specify build mode. Default: debug for Hap/Hsp/Har, release for App |
| `-p debuggable=true/false` | 覆盖 buildOption 中的 debuggable 配置 | | `-p debuggable=true/false` | Override the debuggable setting in buildOption |
| `-p product={ProductName}` | 指定 product 进行编译，默认为 default | | `-p product={ProductName}` | Specify product for compilation, defaults to default |
| `-p module={ModuleName}@{TargetName}` | 指定模块及 target 编译（需配合 `--mode module`） | | `-p module={ModuleName}@{TargetName}` | Specify module and target for compilation (requires `--mode module`) |
| `-p ohos-test-coverage={true\|false}` | 执行测试框架代码覆盖率插桩编译 | | `-p ohos-test-coverage={true\|false}` | Enable test framework code coverage instrumentation |
| `-p parameterFile=param.json` | 设置 oh-package.json5 的参数配置文件 | | `-p parameterFile=param.json` | Set parameter configuration file for oh-package.json5 |
## 构建示例 ## Build Examples
```bash ```bash
# 清理构建产物 # Clean build artifacts
hvigorw clean hvigorw clean
# Debug 模式构建 Hap # Build HAP in debug mode
hvigorw assembleHap -p buildMode=debug hvigorw assembleHap -p buildMode=debug
# Release 模式构建 App # Build APP in release mode
hvigorw assembleApp -p buildMode=release hvigorw assembleApp -p buildMode=release
# 构建指定 product # Build a specific product
hvigorw assembleHap -p product=free hvigorw assembleHap -p product=free
# 构建指定模块 # Build a specific module
hvigorw assembleHap -p module=entry@default --mode module hvigorw assembleHap -p module=entry@default --mode module
# 构建多个模块 # Build multiple modules
hvigorw assembleHar -p module=library1@default,library2@default --mode module hvigorw assembleHar -p module=library1@default,library2@default --mode module
``` ```
## 测试命令 ## Test Commands
### Instrument Test (设备测试) ### Instrument Test (On-Device Test)
```bash ```bash
hvigorw onDeviceTest -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName} hvigorw onDeviceTest -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
``` ```
- `module`: 执行测试的模块，缺省执行所有模块 - `module`: Module to test; omit to test all modules
- `coverage`: 是否生成覆盖率报告，默认 true - `coverage`: Whether to generate coverage report, defaults to true
- `scope`: 测试范围，格式 `{suiteName}#{methodName}` 或 `{suiteName}` - `scope`: Test scope, format `{suiteName}#{methodName}` or `{suiteName}`
- `ohos-debug-asan`: 是否启用 ASan 检测，默认 false (5.19.0+) - `ohos-debug-asan`: Whether to enable ASan detection, defaults to false (5.19.0+)
**输出路径:** **Output paths:**
- 覆盖率报告: `<module-path>/.test/default/outputs/ohosTest/reports` - Coverage report: `<module-path>/.test/default/outputs/ohosTest/reports`
- 测试结果: `<project>/<module>/.test/default/intermediates/ohosTest/coverage_data/test_result.txt` - Test results: `<project>/<module>/.test/default/intermediates/ohosTest/coverage_data/test_result.txt`
### Local Test (本地测试) ### Local Test
```bash ```bash
hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName} hvigorw test -p module={moduleName} -p coverage={true|false} -p scope={suiteName}#{methodName}
``` ```
**输出路径:** **Output paths:**
- 覆盖率报告: `<module-path>/.test/default/outputs/test/reports` - Coverage report: `<module-path>/.test/default/outputs/test/reports`
- 测试结果: `<project>/<module>/.test/default/intermediates/test/coverage_data/test_result.txt` - Test results: `<project>/<module>/.test/default/intermediates/test/coverage_data/test_result.txt`
## 日志级别 ## Log Levels
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `-e, --error` | 设置日志级别为 error | | `-e, --error` | Set log level to error |
| `-w, --warn` | 设置日志级别为 warn | | `-w, --warn` | Set log level to warn |
| `-i, --info` | 设置日志级别为 info | | `-i, --info` | Set log level to info |
| `-d, --debug` | 设置日志级别为 debug | | `-d, --debug` | Set log level to debug |
| `--stacktrace` | 开启打印异常堆栈信息 | | `--stacktrace` | Enable exception stack trace printing |
## 构建分析 (Build Analyzer) ## Build Analyzer
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `--analyze=normal` | 普通模式分析 | | `--analyze=normal` | Normal mode analysis |
| `--analyze=advanced` | 进阶模式，更详细的任务耗时数据 | | `--analyze=advanced` | Advanced mode with detailed task timing data |
| `--analyze=ultrafine` | 超精细化模式，ArkTS 编译详细打点 (6.0.0+) | | `--analyze=ultrafine` | Ultra-fine mode with detailed ArkTS compilation instrumentation (6.0.0+) |
| `--analyze=false` | 不启用构建分析 | | `--analyze=false` | Disable build analysis |
| `--config properties.hvigor.analyzeHtml=true` | 生成 HTML 可视化报告到 `.hvigor/report` | | `--config properties.hvigor.analyzeHtml=true` | Generate HTML visual report to `.hvigor/report` |
## 守护进程 (Daemon) ## Daemon
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `--daemon` | 启用守护进程 | | `--daemon` | Enable daemon process |
| `--no-daemon` | 关闭守护进程（命令行模式推荐） | | `--no-daemon` | Disable daemon process (recommended for CLI mode) |
| `--stop-daemon` | 关闭当前工程的守护进程 | | `--stop-daemon` | Stop the daemon for the current project |
| `--stop-daemon-all` | 关闭所有工程的守护进程 | | `--stop-daemon-all` | Stop all project daemons |
| `--status-daemon` | 查询所有 Hvigor 守护进程信息 | | `--status-daemon` | Query all Hvigor daemon process information |
| `--max-old-space-size=12345` | 设置老生代内存大小 (MB) | | `--max-old-space-size=12345` | Set old generation memory size (MB) |
| `--max-semi-space-size=32` | 设置新生代半空间大小 (MB, 5.18.4+) | | `--max-semi-space-size=32` | Set new generation semi-space size (MB, 5.18.4+) |
## 性能与内存优化 ## Performance and Memory Optimization
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `--parallel` / `--no-parallel` | 开启/关闭并行构建（默认开启） | | `--parallel` / `--no-parallel` | Enable/disable parallel builds (enabled by default) |
| `--incremental` / `--no-incremental` | 开启/关闭增量构建（默认开启） | | `--incremental` / `--no-incremental` | Enable/disable incremental builds (enabled by default) |
| `--optimization-strategy=performance` | 性能优先模式，加快构建但占用更多内存 (5.19.2+) | | `--optimization-strategy=performance` | Performance-first mode, faster builds but higher memory usage (5.19.2+) |
| `--optimization-strategy=memory` | 内存优先模式（默认）(5.19.2+) | | `--optimization-strategy=memory` | Memory-first mode (default) (5.19.2+) |
## 公共命令 ## Utility Commands
| 任务 | 说明 | | Task | Description |
|------|------| |------|-------------|
| `tasks` | 打印工程各模块包含的任务信息 | | `tasks` | Print task information for all project modules |
| `taskTree` | 打印工程各模块的任务依赖关系 | | `taskTree` | Print task dependency graph for all project modules |
| `prune` | 清除 30 天未使用的缓存并删除 pnpm 未引用包 | | `prune` | Clean caches unused for 30 days and remove unreferenced pnpm packages |
| `buildInfo` | 打印 build-profile.json5 配置信息 (5.18.4+) | | `buildInfo` | Print build-profile.json5 configuration information (5.18.4+) |
### buildInfo 扩展参数 ### buildInfo Extended Parameters
```bash ```bash
# 打印工程级配置 # Print project-level configuration
hvigorw buildInfo hvigorw buildInfo
# 打印指定模块配置 # Print configuration for a specific module
hvigorw buildInfo -p module=entry hvigorw buildInfo -p module=entry
# 包含 buildOption 配置 # Include buildOption configuration
hvigorw buildInfo -p buildOption hvigorw buildInfo -p buildOption
# JSON 格式输出 # JSON format output
hvigorw buildInfo -p json hvigorw buildInfo -p json
``` ```
## 其他参数 ## Other Parameters
| 参数 | 说明 | | Parameter | Description |
|------|------| |-----------|-------------|
| `-h, --help` | 打印帮助信息 | | `-h, --help` | Print help information |
| `-v, --version` | 打印版本信息 | | `-v, --version` | Print version information |
| `-s, --sync` | 同步工程信息到 `./hvigor/outputs/sync/output.json` | | `-s, --sync` | Sync project information to `./hvigor/outputs/sync/output.json` |
| `-m, --mode` | 指定执行目录级别 (如 `-m project`) | | `-m, --mode` | Specify execution directory level (e.g., `-m project`) |
| `--type-check` | 开启 hvigorfile.ts 类型检查 | | `--type-check` | Enable type checking for hvigorfile.ts |
| `--watch` | 观察模式，用于预览和热加载 | | `--watch` | Watch mode for preview and hot reload |
| `--node-home <string>` | 指定 Node.js 路径 | | `--node-home <string>` | Specify Node.js path |
| `--config, -c` | 指定 hvigor-config.json5 参数 | | `--config, -c` | Specify hvigor-config.json5 parameters |
## CI/CD 常用命令组合 ## CI/CD Common Command Combinations
```bash ```bash
# 完整的 Release 构建流程 # Full release build pipeline
hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon hvigorw clean && hvigorw assembleApp -p buildMode=release --no-daemon
# 带构建分析的 Debug 构建 # Debug build with build analysis
hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon hvigorw assembleHap -p buildMode=debug --analyze=advanced --no-daemon
# 运行测试并生成覆盖率报告 # Run tests and generate coverage report
hvigorw onDeviceTest -p coverage=true --no-daemon hvigorw onDeviceTest -p coverage=true --no-daemon
# 内存受限环境构建 # Build in memory-constrained environment
hvigorw assembleHap --optimization-strategy=memory --no-daemon hvigorw assembleHap --optimization-strategy=memory --no-daemon
# 清理缓存 # Clean caches
hvigorw prune hvigorw prune
hvigorw --stop-daemon-all hvigorw --stop-daemon-all
``` ```