鸿蒙开发命令行工具介绍
获取 Command Line Tools
Command Line Tools 集合了 HarmonyOS 应用开发所用到的系列工具，包括代码检查 codelinter、堆栈解析 hstack、命令行构建 hvigorw、三方依赖管理 ohpm 和 SDK 中包含的一系列工具，本文主要讲解 codelinter、hstack、hvigorw 等工具的使用方式，关于 SDK 中包含的工具的使用指导请参考 SDK 命令行工具。
下载 Command Line Tools
请前往下载中心获取命令行工具 Command Line Tools，并根据下载中心页面工具完整性指导进行完整性校验。
说明：HarmonyOS SDK 已嵌入命令行工具中，无需额外下载配置。
配置环境变量
将命令行工具进行解压，codelinter、ohpm 等工具存放在 Command Line Tools 的 bin 目录下，需要将该目录配置到 PATH 环境变量中。
Windows
命令行工具解压后，将 ${Command Line Tools解压路径}\command-line-tools\bin 目录配置到系统或者用户的 PATH 环境变量中，配置完成后重新打开命令行窗口。
例如将命令行工具解压到 D 盘根目录，示例如下。
macOS/Linux
将下载后的命令行工具解压到本地。
打开终端工具，执行以下命令，根据输出结果分别执行不同命令。
echo $SHELL
如果输出结果为 /bin/bash，则执行以下命令，打开 .bash_profile 文件。
vi ~/.bash_profile
如果输出结果为 /bin/zsh，则执行以下命令，打开 .zshrc 文件。
vi ~/.zshrc
单击字母“i”，进入 Insert 模式。
输入以下内容，在 PATH 下添加环境变量。请以实际命令行工具解压路径为准。
export PATH=${Command Line Tools解压路径}/command-line-tools/bin:$PATH
编辑完成后，单击 Esc 键，退出编辑模式，然后输入“:wq”，单击 Enter 键保存。
执行以下命令，使配置的环境变量生效。
如果步骤 2 时打开的是 .bash_profile 文件，请执行如下命令：
source ~/.bash_profile
如果步骤 2 时打开的是 .zshrc 文件，请执行如下命令：
source ~/.zshrc
说明：如需验证是否配置成功，可以使用相关命令验证，例如执行 codelinter -v 指令，检查是否可以正确获取 codelinter 工具版本。
HarmonyOS
Command Line Tools 内置 Node.js、SDK、Hvigor、HDC、Ohpm 等工具，用于支撑 DevEco Code 运行、鸿蒙工程编译构建等。
在终端中解压 deveco_tools.tar.gz 包：
tar -xzvf deveco_tools.tar.gz
编辑环境变量文件 ~/.zshrc（如不存在则在个人目录下新建），添加以下内容：
export COMMAND_LINE_TOOL_PATH={解压路径}/deveco_tools
export PATH=$COMMAND_LINE_TOOL_PATH/node/bin:$PATH
保存后执行以下命令使环境变量生效：
source ~/.zshrc
Command Line Tools 内置 Node 为 DevEco Code 标准环境，不建议使用本地已安装的 Node。
代码检查工具（codelinter）
codelinter 同时支持使用命令行执行代码检查与修复，可将 codelinter 工具集成到门禁或持续集成环境中。
codelinter 命令行格式为：
codelinter [options] [dir]
- options：可选配置，请参考表 1。
- dir：待检查的工程根目录；为可选参数，如不指定，默认为当前上下文目录。
表 1 codelinter 命令行配置
| 指令 | 说明 |
|---|---|
--config/-c <filepath> | 指定执行 codelinter 检查的规则配置文件，<filepath> 指定执行检查的规则配置文件位置。 |
--fix | 设置 codelinter 检查同时执行 QuickFix。 |
--format/-f | 设置检查结果的输出格式。目前支持 default/json/xml/html 四种格式；不指定时，默认是 default 格式（文本格式）。 |
--output/-o <filepath> | 指定检查结果保存位置，且命令行窗口不展示检查结果。<filepath> 指定存放代码检查结果的文件路径，支持使用相对/绝对路径。不使用 --output 指令时，检查结果默认会显示在命令行窗口中。 |
--version/-v | 查看 codelinter 版本。 |
--product/-p <productName> | 指定当前生效的 product。<productName> 为生效的 product 名称。 |
--incremental/-i | 对 Git 工程中的增量文件（包含新增/修改/重命名的文件）执行 Code Linter 检查。 |
--language/-l <language> | 设置 codelinter 语言为 cn 或 en。默认为 en。 |
--help/-h | 查询 codelinter 命令行帮助。 |
--exit-on/-e <levels> | 指定哪些告警级别需要返回非零退出码，告警级别包括：error、warn 和 suggestion。若需要指定多个告警级别，级别间需要用英文逗号分开。 |
退出码的计算方式为：用一个 3 位的二进制数从高到低分别表示 error、warn、suggestion 告警级别。若在命令行中配置告警级别，并且代码检查结果中也包含该告警级别，则该二进制值为 1，否则均为 0。将二进制数转换为十进制数，则是退出码。
例如：
- 命令配置为
--exit-on error，代码检查结果包括 error、warn、suggestion 三类告警，则退出码的二进制数为 100，十进制数为 4。 - 命令配置为
--exit-on error，代码检查结果包括 warn、suggestion 两类告警，则退出码的二进制数为 000，十进制数为 0。
进行 codelinter 代码检查与修复。若您的工程存在多个 product，请使用 --product/-p 指令，指定生效的 product 和执行检查的工程根目录。
在工程根目录下使用命令行工具
直接执行 codelinter 指令。此时根据默认 codelinter 检查规则，对该工程中的 TS/ArkTS 文件进行代码检查。默认的规则清单可在检查完成后，根据命令行提示，查看相应位置的 code-linter.json5 文件。
codelinter // 进行codelinter检查
执行如下命令，指定 codelinter 检查所使用的 code-linter.json5 规则配置文件，并进行代码检查。
codelinter -c filepath // 指定执行检查的规则配置文件位置
执行如下命令，对指定工程将根据指定的规则配置文件执行 codelinter 检查，并对部分支持修复的告警信息进行自动修复。
codelinter -c filepath --fix // 对工程中的告警进行修复
在非工程根目录下使用命令行工具
执行如下命令，指定需要进行检查的工程目录或文件路径。此时根据默认 codelinter 检查规则，对该工程中的 TS/ArkTS 文件进行代码检查。默认的规则清单可在检查完成后，根据命令行提示，查看相应位置的 code-linter.json5 文件。
codelinter dir [filepath] [dir1] // 指定执行检查的工程目录或文件路径。支持同时配置多个文件/文件夹路径。 filepath为待检查的文件所在位置，dir、dir1指定待检查的工程目录
在指定的工程目录下，根据指定的 codelinter 规则配置文件进行代码检查。
codelinter -c filepath dir // filepath为指定的规则配置文件所在位置，dir指定执行检查的工程根目录
执行如下命令，对指定工程重新执行 codelinter 检查，并对部分支持修复的告警进行自动修复。
codelinter -c filepath dir --fix // 对指定工程中的告警进行修复。支持配置同时多个工程路径
如需指定检查结果输出格式（以 json 格式为例），执行如下指令。检查结果将在命令行窗口展示。
codelinter [dir] -f json //[dir]为待检查的工程根目录
执行如下指令，指定代码检查输出格式及结果保存位置。此时将不在命令行窗口中打印检查结果，可在指定的文件存放路径下查看。
codelinter [dir] -f json -o filepath2 // [dir]为待检查的工程根目录，filepath2为指定存放代码检查结果的文件路径
ArkTSDoc 文档生成工具（arktsdoc）
简介
从 26.0.0 版本开始，Command Line Tools 集成 arktsdoc 工具，支持通过 arktsdoc 命令行将代码文件中的变量、方法、接口、类等需要对外暴露的信息快速生成相应的参考文档（ArkTSDoc 文档）。
arktsdoc 命令行格式为：
arktsdoc [options] [dir]
- options：可选，命令行的配置参数，具体请参考表 1。
- dir：可选，绝对路径或相对路径。
说明：
若命令行中输入的路径包含 "$"、"|"、"<"、">"、"%"、"^"、","、":"、"="、"*" 等特殊字符，命令可能会解析异常，导致参考文档导出失败。建议用引号包裹路径字符串，或删除路径中的特殊字符。
因操作系统差异导致的参数解析问题，请开发者处理使命令参数符合规格，保证可正常解析。
表 1 arktsdoc 命令行配置参数
| 参数 | 说明 |
|---|---|
--help/-h | 查看 arktsdoc 命令行的帮助信息。 |
--version/-v | 查看 arktsdoc 命令行的版本信息。 |
--workspace/-w | 可选，指定工程根目录，支持绝对路径和相对路径，最多指定一个工程。默认为当前命令行执行的目录。 |
--input/-i | 可选，指定工程/模块/文件/目录的路径，设置 ArkTSDoc 文档的生成范围，支持绝对路径和相对路径（相对于项目路径）。支持指定多个路径，各路径使用英文 ; 分隔，整个路径字符串使用引号包裹。 |
--exclude/-e | 可选，生成 ArkTSDoc 文档时，无需被导出的文件/目录的路径，支持绝对路径和相对路径。支持指定多个路径，各路径使用英文 ; 分隔，整个路径字符串使用引号包裹。支持 Ant 风格的路径匹配模式。在 Ant 风格中，使用 '?' 匹配单字符、'*' 匹配单层目录/文件、'**' 匹配任意层目录等。 |
--destination/-d | 可选，用于指定 ArkTSDoc 文档导出时的存储位置，支持相对路径和绝对路径。默认在当前命令行执行目录下创建一个 output 目录，存放 ArkTSDoc 文档。 |
环境准备
arktsdoc 工具在 Command Line Tools 的 bin 目录下，执行命令前，需要将 bin 目录配置到 PATH 变量中。
使用示例
查看帮助：
arktsdoc -h
Usage: arktsdoc [options] [dir]
Options:
-h, --help Display help for command
-e, --exclude [excludePaths] Indicates the excludePaths of project. Optional.
-i, --input <input> Indicates the input file/directory.
-w, --workspace <path> Indicates the project path of current path.
-d, --destination <path> Indicates the path of the generation result.
-v, --version Display the version number and quit.
查看 arktsdoc 命令行版本：
arktsdoc -v
缺省 options 和 dir：导出当前命令行执行目录下整个工程的 ArkTSDoc 文档，输出到当前目录下的 output 目录中。若当前目录非工程根目录，则会导出失败并提示对应报错信息。
arktsdoc
指定工程根目录：导出指定工程的 ArkTSDoc 文档，输出到该工程下的 output 目录中。若指定目录非工程根目录或目录不存在，则会导出失败并提示对应报错信息。
arktsdoc -w D:\MyApplication
指定目标文件：导出 entry 目录下的 ArkTSDoc 文档，输出到工程下的 output 目录中。如果 entry 目录不存在，则会导出失败并提示对应报错信息。
arktsdoc -w D:\MyApplication -i entry
导出忽略部分目录：导出 entry 目录下的 ArkTSDoc 文档时，无需导出 entry/test 目录，输出到工程下的 output 目录中。如果被忽略目录不存在，则忽略排除指令，正常导出。
arktsdoc -w D:\MyApplication -i entry -e entry/test
指定输出目录：将生成的 ArkTSDoc 文档输出到 D:\doc 目录中。若输入的路径不存在，则会导出失败并提示对应报错信息。
arktsdoc -w D:\MyApplication -i entry -e entry/test -d D:\doc
模拟器工具（Emulator）
从 6.1.0 Release 版本开始，Command Line Tools 集成 Emulator 工具，支持 Windows 和 macOS 平台，可独立进行模拟器创建、启动、关闭、镜像下载等操作。
从 26.0.0 版本开始，支持在 Linux 平台上使用 Emulator，具体使用方式请参考使用 Linux 版本 Emulator 工具。
说明：在 macOS 上使用命令行工具时，如果弹框提示 Emulator 无法验证开发者，可以在系统的设置 > 隐私与安全性中选择仍要打开 Emulator，或者使用 DevEco Studio 目录下的 Emulator 工具。
环境准备
Emulator 工具在 command-line-tools 安装目录的 emulator 目录下，有两种执行命令的方式。
方式一：在命令行终端中进入 emulator 目录下，执行命令。
方式二：配置环境变量后，在任意目录下执行命令。
Windows 环境变量设置方法：
在系统或者用户的 PATH 变量中，添加路径 {command-line-tools安装目录}/emulator，配置完成后重新打开命令行窗口使环境变量生效。
macOS/Linux 环境变量设置方法：
打开命令行终端，执行以下命令。
export PATH={command-line-tools安装目录}/emulator:$PATH
模拟器命令
Emulator 命令请参考通过命令行使用模拟器。
在模拟器上推包调试
可通过 hdc 工具在模拟器上进行推包调试。
使用时需要先确认模拟器和 hdc 的连接状态，模拟器的 IP 和端口号是 127.0.0.1:5555，如果端口号已经被占用，则从 5555 起递增 2，例如 5555、5557、5559，端口号范围在 5555-15555 之间。
hdc list targets
如果未连接，执行命令 hdc tconn {IP:端口号} 连接模拟器，例如：
hdc tconn 127.0.0.1:5555
连接成功后，通过 hdc 在模拟器上安装、卸载应用等，更多使用方式请参考 SDK 命令行工具。
使用 Linux 版本 Emulator 工具
从 26.0.0 版本开始，支持在 Linux 平台使用模拟器工具。
环境准备
当前仅支持 Ubuntu 18.04 及以上的 Linux 系统，使用前需要安装相关的依赖，以 Ubuntu 18.04 操作系统为例，执行命令：
apt install -y libatomic1 libpulse0 libegl1 libgbm1 libgl1 libpng16-16 libfontconfig1 libfreetype6 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-xinerama0 libxcb-xkb1 libsm6 libice6 libxkbcommon-x11-0 libxkbcommon0 libglib2.0-0
使用约束
- Linux 模拟器依赖系统 kvm 能力，需要手动将 Emulator 程序当前用户加入
/dev/kvm所在的组中。 - Linux 模拟器图形渲染依赖
/dev/dri下的设备渲染节点，如 card0、renderD128 等，需要手动将 Emulator 程序当前用户加入相关节点的用户组中。 - 如需使用第三方远程桌面工具操作 Linux，请确保工具可使用的图形驱动支持 OpenGL4.1 或以上版本。
模拟器命令差异
针对无图形界面的 Linux 环境，启动模拟器命令必须添加 -noWindow 参数。除此之外，其他命令和 Windows/macOS 相同，详细命令请参考通过命令行使用模拟器。
命令行构建工具（hvigorw）
hvigorw 作为 Hvigor 的 wrapper 包装工具，支持自动安装 Hvigor 构建工具和相关插件依赖，以及执行 Hvigor 构建命令。
执行命令前，需要先配置 JDK，配置 Node.js、hvigor 等环境变量，具体请参考搭建流水线。
命令行使用方式
hvigorw 命令行格式为：
hvigorw [taskNames...] <options>
其中 taskNames 是任务，可同时执行多个任务，options 是可选参数，具体的任务和可选参数请参考常用命令。
说明：从 hvigorw 5.18.4 版本开始，以下命令支持在任意路径下执行，其他 hvigorw 命令需要在工程根目录下执行。
hvigorw -v
hvigorw --version
hvigorw version
hvigorw -h
hvigorw --help
常用命令
查询
| 参数 | 说明 |
|---|---|
-h, --help | 打印 hvigorw 的命令帮助信息。 |
-v, --version, version | 打印 hvigorw 版本信息。 |
编译构建
| 任务 | 说明 |
|---|---|
clean | 清理构建产物 build 目录。 |
collectCoverage | 基于打点数据生成覆盖率统计报表。 |
assembleHap | 构建 Hap 应用。 |
assembleApp | 构建 App 应用。 |
assembleHsp | 构建 Hsp 包。 |
assembleHar | 构建 Har 包。 |
编译构建命令行常用扩展参数：
| 参数 | 说明 |
|---|---|
| `-p buildMode={debug | release}` |
-p debuggable=true/false | 该配置会覆盖构建模式中对应的 buildOption 中的 debuggable 配置。关于 debuggable 的合并优先级，请参考合并编译选项规则。 |
-p product={ProductName} | 指定 product 进行编译，编译 product 下配置的 module target。缺省时：默认为 default。 |
-p module={ModuleName}@{TargetName} | 指定模块及 target 进行编译，可指定多个相同类型的模块进行编译，以逗号隔开；TargetName 不指定时默认为 default。限制：此参数需要与 --mode module 参数搭配使用。缺省时：执行 AssembleHap 任务会编译工程下所有模块，默认指定 target 为 default。 |
| `-p ohos-test-coverage={true | false}` |
| `-p coverage={true | false}` |
-p parameterFile=param.json/json5 | 设置 oh-package.json5 文件的参数配置文件，其中 "param" 可自行修改为对应配置文件名称。详细使用请参考 parameterFile。 |
-p buildVersion=1 | 设置构建版本号为 1，详细使用请参考 app.json5 的 buildVersion。该参数从 hvigorw 6.23.3 版本开始支持。 |
日志
| 参数 | 说明 |
|---|---|
-e, --error | 设置 Hvigor 的日志级别为 error。 |
-w, --warn | 设置 Hvigor 的日志级别为 warn。 |
-i, --info | 设置 Hvigor 的日志级别为 info。 |
-d, --debug | 设置 Hvigor 的日志级别为 debug。 |
--stacktrace，--no-stacktrace | Hvigor 默认关闭打印所有异常的堆栈信息，如需开启在命令行后添加 --stacktrace。 |
可视化
| 参数 | 说明 |
|---|---|
--analyze=normal | 在 DevEco Studio 中开启 Build Analyzer 构建分析，设置为普通模式，通过简单打点数据进行分析。 |
--config properties.hvigor.analyzeHtml=true | 在工程的 .hvigor/report 目录下生成构建可视化 html 文件，该文件可直接在浏览器中打开。 |
--analyze=false | 不启用 Build Analyzer 构建分析。 |
--analyze=advanced | 启用 Build Analyzer 构建分析，并设置为进阶模式，通过更加详细的打点数据进行分析。如果需要更详细的任务耗时数据，请选择该模式。 |
--analyze=ultrafine | 启用 Build Analyzer 构建分析，并设置为超精细化模式，与 advanced 模式相比，在 ArkTS 编译阶段记录更详细的打点数据，但开启后可能导致编译构建时间更长。从 hvigorw 6.0.0 版本开始支持。 |
--analyze | 同 --analyze=normal 命令。从 hvigorw 4.3.0 开始废弃，请使用 --analyze=normal 替换。 |
--no-analyze | 同 --analyze=false 命令。从 hvigorw 4.3.0 开始废弃，请使用 --analyze=false 替换。 |
--verbose-analyze | 同 --analyze=advanced 命令。从 hvigorw 4.3.0 开始废弃，请使用 --analyze=advanced 替换。 |
daemon
| 参数 | 说明 |
|---|---|
--daemon | 启用守护进程。 |
--no-daemon | Hvigor 默认启用守护进程，如需关闭，可在命令行后添加该选项。命令行模式下推荐使用此参数。 |
--stop-daemon | 关闭当前工程的守护进程。 |
--stop-daemon-all | 关闭所有工程的守护进程。 |
--status-daemon | 查询当前环境中所有的 Hvigor 守护进程信息。 |
--max-old-space-size=12345 | 设置守护进程最大的老生代内存大小为 12345MB。 |
--max-semi-space-size=32 | 设置守护进程新生代内存最大的半空间大小为 32MB。该参数从 hvigorw 5.18.4 版本开始支持。 |
性能/内存
| 参数 | 说明 |
|---|---|
--parallel, --no-parallel | Hvigor 默认开启并行构建能力，如需关闭在命令行后添加 --no-parallel。 |
--incremental, --no-incremental | Hvigor 默认开启增量构建能力，如需关闭在命令行后添加 --no-incremental。 |
--optimization-strategy=performance | 设置构建模式为性能优先模式，可加快构建速度，但会占用更多内存。从 hvigorw 5.19.2 版本开始支持。 |
--optimization-strategy=memory | 设置构建模式为内存优先模式，可以减少编译内存占用，默认使用 memory。从 hvigorw 5.19.2 版本开始支持。 |
公共命令
| 任务 | 说明 |
|---|---|
tasks | 打印工程各模块包含的任务信息。 |
taskTree | 打印工程各模块的任务依赖关系信息。 |
prune | 清除 30 天内未使用的 Hvigor 缓存文件并从 pnpm 存储中删除未引用的包。 |
buildInfo | 打印工程级或模块级 build-profile.json5 中的配置信息，包含 product、module、target、buildMode、buildOption，以树状结构输出。该功能从 hvigorw 5.18.4 版本开始支持。 |
buildInfo 命令扩展参数：
| 参数 | 说明 |
|---|---|
-p module={ModuleName} | 指定需要打印配置信息的模块名，不指定时会打印工程级的配置信息。 |
-p buildOption | 命令包含此参数时会打印 buildOption 配置，不含此参数时将不会展示 buildOption 配置，输出的 buildOption 优先级请参考合并编译选项规则。 |
-p json | 将输出结果以 json 格式展示。 |
其他命令
| 参数 | 说明 |
|---|---|
-s,--sync | 处理并持久化 Hvigor 部分工程信息到工程 ./hvigor/outputs/sync/output.json 中。 |
--syncNative | 在 sync 阶段执行 syncNative，可替换 compileNative 任务执行，完成并行编译，详细请参考通过 syncNative 提升 sync 阶段 C++ 编译效率。 |
-m,--mode | 在对应的目录执行相应的 task，例 hvigorw clean -m project 在工程目录下执行 build 目录清理（即清理工程级别的 build 文件夹）。 |
--enable-build-script-type-check | 开启工程中 hvigorfile.ts 的类型检查，该字段已废弃，请使用 --type-check 替换。 |
--type-check, --no-type-check | Hvigor 默认关闭工程中 hvigorfile.ts 的类型检查，如需开启，可在命令行后添加 --type-check。 |
--no-pnpm-frozen-lockfile，--pnpm-frozen-lockfile | Hvigor 默认不忽略 pnpm-lock.yaml 文件，如需忽略，可在命令行后添加 --pnpm-frozen-lockfile。忽略 pnpm-lock.yaml 文件，按照 hvigor-config.json5 的配置安装 Hvigor 插件的依赖（如果不忽略 pnpm-lock.yaml 文件，在使用 Hvigor 2.0.0 及以上版本的 CI 场景下安装 Hvigor 插件依赖时将报错）。说明：该命令在 4.1 Release 及以上版本中已废弃。在 CI 场景中将自动配置，无需开发者手动配置。 |
--config, -c | 指定 hvigor-config.json5 配置文件中的参数。当前仅支持设置 properties 里的参数，具体支持的参数请查看 hvigor-config.json5 文件中 properties 支持的参数。--config properties.key=value 同 -c properties.key=value。 |
--watch | 开启观察模式，主要用于预览和热加载场景。 |
--generate-build-profile, --no-generate-build-profile | 已废弃。生成 BuildProfile.ets 文件。 |
--node-home <string> | 指定 nodejs 路径。 |
hvigorw 常用示例
hvigorw -v
hvigorw --version
hvigorw version
hvigorw -h
hvigorw --help
hvigorw clean
hvigorw assembleHap
hvigorw assembleApp
hvigorw assembleHsp
hvigorw assembleHar
hvigorw assembleHap -p buildMode=debug
hvigorw assembleApp -p buildMode=release
hvigorw assembleHap -p product=default
hvigorw assembleHap -p module=entry@default --mode module
hvigorw --analyze=normal
hvigorw --config properties.hvigor.analyzeHtml=true
hvigorw --daemon
hvigorw --no-daemon
hvigorw tasks
hvigorw taskTree
hvigorw prune
hvigorw buildInfo -p module=entry -p buildOption -p json
堆栈解析工具（hstack）
简介
hstack 是为开发人员提供的用于将 release 应用混淆后的 crash 堆栈解析为源码对应堆栈的工具，支持 Windows、Mac、Linux 三个平台，关于堆栈解析的原理，请查看异常堆栈解析原理。
hstack 命令行格式为：
hstack [options]
options：可选配置，请参考表 hstack 命令行配置。
表 1 hstack 命令行配置
| 指令 | 说明 |
|---|---|
-i/--input | 可选，指定工程 crash 文件归档目录。从 26.0.0 版本开始，支持指定 crash 文件。 |
-c/--crash | 可选，指定一条 crash 堆栈。 |
-o/--output | 可选，指定解析结果输出目录或输出文件。通过 -i 指定输入目录时，-o 参数指定输出目录。如果不指定，默认输出到 -i 指定的目录下。通过 -i 指定输入文件时，-o 参数指定输出目录或文件。如果不指定，默认输出到 -i 所在的文件目录下。通过 -c 指定输入堆栈时，-o 参数指定输出文件。如果不指定，默认输出到控制台。 |
-s/--sourcemapDir | 可选，指定工程 sourceMap 文件归档目录。从 26.0.0 版本开始，支持指定 sourceMap 文件。 |
--so/--soDir | 可选，指定工程 shared object 文件归档目录。从 26.0.0 版本开始，支持指定 shared object 文件。 |
-n/--nameObfuscation | 可选，指定工程 nameCache 文件归档目录。从 26.0.0 版本开始，支持指定 nameCache 文件。 |
-v/--version | 查看 hstack 版本。 |
-h/--help | 查询 hstack 命令行帮助。 |
说明：
- crash 文件/文件归档目录与 crash 堆栈必须且只能提供一项。
- sourceMap 与 shared object 文件/文件归档目录至少提供一项。
- 如果需要对方法名进行解析还原，则需要同时提供 sourceMap 与 nameCache 文件。
- 路径参数不支持以下特殊字符：
~!@#$^&*=|{};,\s\[\]<>?~！@#￥……&*（）——|{}【】‘；：。，、？
环境准备
hstack 工具在 Command Line Tools 的 bin 目录下，需要将 bin 目录配置到 PATH 变量中。
如果需要对 C++ 文件产生的异常进行解析，则需要将 SDK 中的 native\llvm\bin 目录配置到环境变量中，变量名设置为 ADDR2LINE_PATH。
使用示例
将应用产生的 crash 文件归档到 crashDir 目录下（或者 -c 指定一条 crash 堆栈），关于堆栈的获取方式请参考崩溃检测。
使用 -o 指定输出目录，当不指定时，会输出至 -i 指定的 crashDir 目录下（通过 -c 输入为 crash 堆栈时，可以使用 -o 指定一个输出文件，或不指定，直接将结果输出至控制台）。
使用 -s 指定工程对应 sourceMap 文件归档目录（可选，与 shared object 文件归档目录至少提供一项）。
使用 --so 指定 shared object 文件归档目录（可选，与 sourceMap 归档目录至少提供一项）。
使用 -n 指定 nameCache 文件归档目录（可选）。
执行以下命令，可将 release 应用 crash 堆栈解析为源码对应堆栈。
# 通过-i指定crash文件归档目录，并将解析结果输出至outputDir目录
hstack -i D:\crashDir -o D:\outputDir -s D:\sourcemapDir --so D:\soDir -n D:\nameCacheDir
# 通过-c指定一条堆栈，并将解析结果输出至out.txt文件
hstack -c "at anonymous (entry|entry|1.0.0|src/main/ets/pages/Index.ts:401:1)" -o D:\outputDir\out.txt -s D:\sourcemapDir --so D:\soDir -n D:\nameCacheDir
如果是指定 crash 文件归档目录，解析完成后，outputDir 目录下会生成对应的解析结果，文件以原始 crash 文件名加 _ 前缀进行命名。crash 堆栈中的 C++ 日志以及 ArkTS 日志均已解析为源码对应的文件路径以及行列号，结果如下图所示：
在构建 Release 应用时，so 文件是默认不包含符号表信息的，如果需要在构建 Release 应用时生成包含符号表的 so 文件，需要在工程的模块级 build-profile.json5 文件的 buildOption 属性中，配置如下信息：
"buildOption": {
"externalNativeOptions": {
"arguments": "-DCMAKE_BUILD_TYPE=RelWithDebInfo"
}
}
堆栈解析方案说明
以如下代码为例。
Entry 模块通过独立 har 包形式引用 har 模块中的 har 方法：
import {har} from 'Har'
@Entry
@Component
struct Index {
@State har: string = 'Har';
build() {
Row() {
Column() {
Text(this.har)
.fontSize(50)
.fontWeight(FontWeight.Bold)
.onClick(() => {
let entryClass = new EntryClass();
entryClass.callHarFunction();
})
}
.width('100%')
}
.height('100%')
}
}
class EntryClass {
callHarFunction() {
har()
}
}
@Component
export struct MainPage {
@State message: string = 'Hello World';
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
}
.width('100%')
}
.height('100%')
}
}
export function har() {
BigInt(1.1)
}
生成的 crash 如下：
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 anonymous (entry|entry|1.0.0|src/main/ets/pages/Index.ts:55:55)
crash 中，包含混淆后的方法名（或属性名）、路径信息以及混淆后的行列号信息，其中：
- 方法名在配置相应混淆规则后，会进行混淆处理（例如上述例子中 EntryClass 的 callHarFunction 被混淆为 i）。方法名混淆前后的映射关系保存在对应模块编译产物的 nameCache 文件中。
- 路径信息格式为：引用方 entry-packageName|被引用方 packageName|version|源码相对路径，其中 packageName 以及 version 保存在对应模块编译产物的 sourceMap 文件中。
- 行列号混淆前后的映射关系保存在对应模块编译产物的 sourceMap 文件中，可利用文件对应的 mappings 字段进行解析还原。
在对堆栈进行还原时，可分为以下三步：
根据路径信息，找到引用方模块 sourceMap。例如第一条堆栈：
at har (entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js:58:58)
根据路径信息 entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js，可在 entry 模块 sourceMap 文件中找到如下字段：
"entry|har|1.0.0|src/main/ets/components/mainpage/MainPage.js": {
"version": 3,
"file": "MainPage.js",
"sources": [
"oh_modules/.ohpm/Har@ue9rwlwgmslvadnmypsedjcin6a=/oh_modules/Har/src/main/ets/components/mainpage/MainPage.js"
],
"names": [],
"mappings": "AAAA,IAAA,CAAA,CAAA,sBAAA,IAAA,MAAA,CAAA,SAAA,CAAA,EAAA;IACA,OAAA,CAAA,GAAA,CAAA,MAAA,CAAA,SAAA,EAAA,sBAAA,EAAA,GAAA,EAAA,GAAA,CAAA,CAAA,CAAA;CACA;AACA,MAAA,OAAA,QAAA,SAAA,MAAA;IACA,YAAA,CAAA,EAAA,EAAA,EAAA,CAAA,EAAA,CAAA,GAAA,CAAA,CAAA,EAAA,CAAA,GAAA,SAAA,EAAA,CAAA;QACA,KAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,CAAA,CAAA;QACA,IAAA,OAAA,CAAA,KAAA,UAAA,EAAA;YACA,IAAA,CAAA,gBAAA,GAAA,CAAA,CAAA;SACA;QACA,IAAA,EAAA,GAAA,IAAA,wBAAA,CAAA,aAAA,EAAA,IAAA,EAAA,SAAA,CAAA,CAAA;QACA,IAAA,CAAA,yBAAA,IAAA,CAAA;QACA,IAAA,CAAA,oBAAA,EAAA,CAAA;IACA,CAAA;IACA,yBAAA,CAAA,EAAA;QACA,IAAA,GAAA,OAAA,KAAA,SAAA,EAAA;YACA,IAAA,CAAA,OAAA,GAAA,GAAA,OAAA,CAAA;SACA;IACA,CAAA;IACA,eAAA,CAAA,CAAA;IACA,CAAA;IACA,iCAAA,CAAA,CAAA;QACA,IAAA,EAAA,CAAA,uBAAA,CAAA,CAAA,CAAA,CAAA;IACA,CAAA;IACA,gBAAA;QACA,IAAA,EAAA,CAAA,gBAAA,EAAA,CAAA;QACA,iBAAA,CAAA,GAAA,EAAA,CAAA,MAAA,CAAA,IAAA,CAAA,IAAA,EAAA,CAAA,CAAA;QACA,IAAA,CAAA,wBAAA,EAAA,CAAA;IACA,CAAA;IACA,IAAA,OAAA;QACA,OAAA,IAAA,EAAA,CAAA,GAAA,EAAA,CAAA;IACA,CAAA;IACA,IAAA,OAAA,CAAA,EAAA;QACA,IAAA,EAAA,CAAA,GAAA,IAAA,CAAA;IACA,CAAA;IACA,aAAA;QACA,IAAA,CAAA,yBAAA,CAAA,CAAA,CAAA,EAAA,EAAA,EAAA,EAAA;YACA,GAAA,CAAA,MAAA,EAAA,CAAA;YACA,GAAA,CAAA,MAAA,CAAA,MAAA,CAAA,CAAA;QACA,CAAA,EAAA,GAAA,CAAA,CAAA;QACA,IAAA,CAAA,yBAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAA,EAAA;YACA,MAAA,CAAA,MAAA,EAAA,CAAA;YACA,MAAA,CAAA,KAAA,CAAA,MAAA,CAAA,CAAA;QACA,CAAA,EAAA,MAAA,CAAA,CAAA;QACA,IAAA,CAAA,yBAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAA,EAAA;YACA,IAAA,CAAA,MAAA,CAAA,IAAA,CAAA,OAAA,CAAA,CAAA;YACA,IAAA,CAAA,QAAA,CAAA,EAAA,CAAA,CAAA;YACA,IAAA,CAAA,UAAA,CAAA,UAAA,CAAA,IAAA,CAAA,CAAA;QACA,CAAA,EAAA,IAAA,CAAA,CAAA;QACA,IAAA,CAAA,GAAA,EAAA,CAAA;QACA,MAAA,CAAA,GAAA,EAAA,CAAA;QACA,GAAA,CAAA,GAAA,EAAA,CAAA;IACA,CAAA;IACA,QAAA;QACA,IAAA,CAAA,mBAAA,EAAA,CAAA;IACA,CAAA;CACA;AACA,MAAA,UAAA,GAAA;IACA,MAAA,CAAA,GAAA,CAAA,CAAA;AACA,CAAA",
"entry-package-info": "entry|1.0.0",
"package-info": "har|1.0.0"
}
利用对应 sourceMap 信息进行堆栈路径以及行列号还原：
基于步骤 1 找到的 sourceMap 信息，根据 sources 及 mappings 字段进行解析，可以将路径以及行列号还原如下：
at har (oh_modules/.ohpm/Har@ue9rwlwgmslvadnmypsedjcin6a=/oh_modules/Har/src/main/ets/components/mainpage/MainPage.js:58:58)
该文件位于 entry 模块 oh_modules 路径下。
如果对应 sourceMap 中包含 package-info 字段，则可以利用 package-info 中对应模块的 sourceMap，对该条堆栈进行二次解析。例如该堆栈中包 package-info 为 har|1.0.0，可利用 har 中的 sourceMap 对该堆栈进行再次解析，方案如下：
由路径中最后一个 oh_modules 起，向下两级，截断上述第一次解析结果路径，结果如下：
src/main/ets/components/mainpage/MainPage.js
上述路径拼接 package-info，拼接方式为：packageName|packageName|version|截断路径，得到拼接路径如下：
har|har|1.0.0|src/main/ets/components/mainpage/MainPage.js
利用拼接后的路径，在 har 模块 sourceMap 文件中找到如下字段：
"har|har|1.0.0|src/main/ets/components/mainpage/MainPage.js": {
"version": 3,
"file": "MainPage.ets",
"sources": [
"har/src/main/ets/components/mainpage/MainPage.ets"
],
"names": [],
"mappings": ";;;AAEA,MAAA,OAAA,QAAA,SAAA,MAAA;IADA,YAAA,CAAA,EAAA,CAAA,EAAA,CAAA,EAAA,IAAA,CAAA,CAAA,EAAA,IAAA,SAAA,EAAA,CAAA;;;;;;;;IADyB,CAAA;;;;;;;;;;;;;;;;;;;;;;IAKvB,aAAA;;;;;;;;;;;;YAGM,IAAA,CAAA,UAAA,CAAA,UAAA,CAAA,IAAA,CAAA,CAAA;;;;;IAOL,CAAA;;;;;AAGH,MAAA,UAAA,GAAA;;AAEA,CAAA",
"entry-package-info": "har|1.0.0"
}
根据该 sourceMap 的 sources 及 mappings 字段进行再次解析，可得到该堆栈对应的源码信息为：
at har (har/src/main/ets/components/mainpage/MainPage.ets:20:1)
利用 nameCache 文件，对方法名进行解析还原。
以第二条堆栈为例：
at i (entry|entry|1.0.0|src/main/ets/pages/Index.ts:71:71)
通过步骤 1 与步骤 2，将该堆栈路径以及行列号信息进行解析，结果如下：
at i (entry/src/main/ets/pages/Index.ets:25:3)
在对应模块编译产物中的 nameCache 文件中，通过解析后的文件路径找到如下字段：
"entry/src/main/ets/pages/Index.ets": {
"IdentifierCache": {
"Index#initialRender#__function": "o",
"Index#initialRender#$2#__function": "t",
"Index#initialRender#$2#$0#entryClass": "u",
"$0#__function": "a1"
},
"MemberMethodCache": {
"initialRender:6:20": "initialRender",
"callHarFunction:24:26": "i"
},
"obfName": "entry/src/main/ets/pages/Index.ets"
}
该字段的 IdentifierCache 与 MemberMethodCache 中保存了方法名混淆前后的映射关系，对应格式为：
"源码方法名:该方法起始行号:该方法结束行号":"混淆后方法名"。
第二条堆栈混淆后的方法名为 "i"，利用上述字段对该方法名进行还原：
在上述字段中找出所有混淆后方法名为 "i" 的条目，可能存在多个，该字段中为：
"callHarFunction:24:26": "i"
找到行号范围包含步骤 2 中还原后行号的条目，根据步骤 2 得到还原后的行号为 25，包含在 24-26 之内，因此可以得到源码对应方法名为 "callHarFunction"。
通过上述方式，可以得到源码的方法名。
步骤 2 与步骤 3 所得结果进行整合，得到最终堆栈结果如下：
at har (har/src/main/ets/components/mainpage/MainPage.ets:20:1)
at callHarFunction (entry/src/main/ets/pages/Index.ets:25:3)
at anonymous (entry/src/main/ets/pages/Index.ets:14:47)
通过上述方式，即可利用编译产物对 release 应用的 crash 信息进行解析还原。
三方依赖管理工具（ohpm）
ohpmrc
ohpm 配置文件。
描述
ohpm 从命令行和 .ohpmrc 文件中获取其配置内容。ohpm config 命令可用于修改用户级 .ohpmrc 文件的内容。
文件
- 项目级配置文件：
/path/to/my/project/.ohpmrc - 用户级配置文件：
~/.ohpm/.ohpmrc
所有 ohpm 配置文件均是 ini 格式：<key>= <value> 的参数列表。
注意：
- 命令行工具会优先读取项目级的配置文件。如果缺少某些配置项，将从用户级配置文件中读取缺失的配置项信息。
- 在工程任意子目录下执行 ohpm 命令，都可以读取到项目级的
.ohpmrc配置。
注释
.ohpmrc 文件中以 "#" 或 ";" 字符为注释符。
更新配置
执行如下命令可设置用户级配置：
ohpm config set key value
默认配置项
| 配置项 | 字段名称 | 字段说明 | 字段类型 | 默认值 | 备注 |
|---|---|---|---|---|---|
| 仓库设置 | registry | 下载仓库 | 字符串 | https://ohpm.openharmony.cn/ohpm/ | 支持配置多个仓库地址，以英文逗号分隔。系统将按照配置的先后顺序依次检索这些仓库，直到成功下载目标包。例如：当需要下载包 a 时，会优先从第一个配置的仓库地址查找，若未找到则自动尝试下一个仓库，依此类推。 |
| 仓库设置 | @group:registry | 指定仓库 | 字符串 | "" | 根据 group 指定组织的仓库地址。支持配置多个仓库地址，以英文逗号间隔，且优先级大于 registry 配置，系统将按照配置的先后顺序依次检索这些仓库，直到成功下载目标包。 |
| 发布设置 | publish_registry | 发布仓库 | 字符串 | https://ohpm.openharmony.cn/ohpm/ | 配置发布的仓库地址，仅支持配置一个仓库地址。 |
| 发布设置 | publish_id | 用户发布号 | 字符串 | "" | 用户发布号，用来发布三方库，全局唯一。 |
| 路径设置 | cache | 缓存路径 | 字符串 | ~/.ohpm/cache | - |
| 路径设置 | key_path | 私钥路径 | 字符串 | "" | 利用 ssh-keygen 工具生成的私钥的放置路径地址。 |
| 路径设置 | crypto_path | 加密组件路径 | 字符串 | "" | 加密组件路径地址。详情请见：crypto_path。 |
| 网络设置 | no_proxy | 不使用 proxy 代理 | 字符串 | "" | 配置不使用代理的仓库地址，可配置多个，以英文逗号间隔；值可以是域名或者 ip，支持二级域名通配符 *（例如：*.huawei.com）。 |
| 网络设置 | http_proxy | http 代理 | 字符串 | "" | 支持用户名和密码的网络代理，特殊字符需要转义。示例：http://proxy_server:port、http://username:password@proxy_server:port。 |
| 网络设置 | https_proxy | https 代理 | 字符串 | "" | 支持用户名和密码的网络代理，特殊字符需要转义。示例：https://proxy_server:port、http://username:password@proxy_server:port。 |
| 网络设置 | strict_ssl | ssl 校验 | 布尔 | true | 默认值为 true，校验 https 证书；若配置为 false，则不校验 https 证书。 |
| 网络设置 | ca_files | ca 证书路径 | 字符串 | "" | strict_ssl=true 时校验服务端证书需要的 ca 证书放置路径，可以放置多个证书路径，以英文逗号间隔。详情请见：CA 证书获取及配置。 |
| 网络设置 | fetch_timeout | 请求超时时间 | 数值 | 60000 | 取值范围：[10000，360000]，单位为毫秒。如果设置的 fetch_timeout 值不在取值范围内，则默认为：60000。 |
| 并发设置 | max_concurrent | 最大并发量 | 数值 | 50 | 取值范围：[1, 200]，设置每个模块在安装时允许的最大并发量。 |
| 并发设置 | retry_times | 出错重试次数 | 数值 | 1 | 取值范围：[0, 5]，针对白名单内的异常，程序会按配置重试指定次数，白名单有：ECONNRESET：连接被对端重置；ECONNREFUSED：连接被服务器拒绝；ETIMEDOUT：连接超时；RESPONSETIMEOUT：响应超时；TARBADARCHIVE：包格式异常。 |
| 并发设置 | retry_interval | 出错重试间隔时间 | 数值 | 1000 | 取值范围：[1000, 60000]，单位毫秒。 |
| 依赖冲突设置 | resolve_conflict | 开启自动解决依赖版本冲突功能 | 布尔 | true | 默认开启。当设置为 true 或缺省时，ohpm 会自动处理依赖版本冲突，详情请见：resolve_conflict。 |
| 依赖冲突设置 | resolve_conflict_strict | 开启严格模式依赖冲突处理功能 | 布尔 | false | 默认关闭。当设置为 true 时，ohpm 会按照严格模式处理依赖版本冲突，详情请见：resolve_conflict_strict。 |
| 安全设置 | key_passphrase | 已加密的私钥密码 | 字符串 | "" | 默认为空，使用加密命令将私钥密码加密，执行涉及公私钥的认证命令时，自动使用 key_passphrase 对私钥文件进行解密，无需用户手动输入私钥密码。详情请见：key_passphrase。 |
| 其他设置 | log_level | 日志级别 | 字符串 | info | 可设置日志输出级别，对应级别类型有 debug、info、warn、error。详情请见：log_level。 |
| 其他设置 | install_all | 是否安装工程所有模块的依赖 | 布尔 | true | 默认为 true。当设置为 true 或缺省时，在执行 ohpm install、ohpm update、ohpm uninstall 时，将会安装工程下所有模块的依赖。详情请见 install_all。 |
| 其他设置 | :_auth 和 :_read_auth | AccessToken 配置项 | 字符串 | 无 | ohpm-repo 支持使用 access token 进行认证。详情请见 AccessToken。 |
| 其他设置 | enforce_dependency_key | 开启依赖名称校验 | 布尔 | false | 默认为 false。设置为 true 后，ohpm 会校验配置的本地依赖名称与其对应的包名是否一致，若不一致会导致命令执行失败。详情请见 enforce_dependency_key。 |
| 其他设置 | ensure_dependency_include | 开启依赖扫描功能 | 布尔 | false | 默认为 false。从 ohpm 1.7.0 开始，在执行 ohpm publish 命令时，会检查发布包的源码中，静态导入的三方依赖是否都声明在 oh-package.json5 的 dependencies 或 dynamicDependencies 中。若缺少依赖声明且字段设置为 false 时，会提示相应告警信息；设置为 true 时，则会使命令执行失败并提示错误信息。详情请见 ensure_dependency_include。 |
| 其他设置 | projectPackageJson:<project_root> | 工程 oh-package.json5 配置覆盖 | 字符串 | 无 | 用于覆盖工程根目录下 oh-package.json5 中的配置。配置项名称中的 <project_root> 表示工程根目录路径（根据实际情况替换为真实的工程根目录路径）。配置项的值为指定的工程级 oh-package.json5 文件的路径，支持使用相对路径（当使用相对路径时，根路径为 <project_root>）。详情请见 .ohpmrc 中 projectPackageJson 配置。 |
| 其他设置 | disallow_nested_package | 开启包内 .har/.tgz 依赖配置路径检测 | 布尔 | false | 默认为 false。设置为 true 后，在执行 prepublish/publish 时，会扫描包内是否存在 './' 形式配置且后缀为 .har/.tgz 格式的依赖，如果存在，则会使命令执行失败并提示报错信息。详情见 disallow_nested_package。 |
| 其他设置 | odm_r2_project_root | 开启 overrideDependencyMap 中相对路径自动转换功能 | 布尔 | false | 默认为 false。设置为 true 后，当存在 overrideDependencyMap 配置且其配置项对应的配置文件内存在相对路径的依赖配置时，ohpm 会基于工程根路径解析来查找这些相对路径。详情见 odm_r2_project_root。 |
| 其他设置 | enable_cross_process_lock | 启用跨进程锁 | 布尔 | false | 默认为 false。由于 oh_modules 目录结构限制，ohpm 不支持在同一个工程下并行运行多个 ohpm install、ohpm update 或 ohpm uninstall 命令，若需要在同一个工程下执行多个 ohpm install、ohpm update 或 ohpm uninstall 命令，则必须将该配置设置为 true，以保证这多个命令以串行的方式运行。 |
| 其他设置 | compability_log_level | 兼容性字段检测日志等级 | 字符串 | warn | 默认为 warn。在执行 prepublish、publish 命令时，ohpm 会检测 oh-package.json5 文件中是否配置了兼容性检测需要的所有字段（compatibleSdkVersion, compatibleSdkType, obfuscated, nativeComponents），如果未配置，则会根据日志等级打印提示或报错。详情请见 compability_log_level。 |
| 其他设置 | use_stream_threshold_size | 流式上传阈值 | 数值 | 5 | 取值范围：[0, 300]，单位 mb。当 publish 三方库的文件体积大于此阈值时将会使用流式上传三方库，如果仓库不存在流式上传接口则自动转为 Base64 方式上传。 |
| 其他设置 | lockfile_stable_order | oh-package-lock.json5 内容稳定排序 | 布尔 | false | 默认为 false。若设置为 true，会确保在 oh-package.json5 文件未变更时，当前已生成的 oh-package-lock.json5 各字段内容不变。 |
| 其他设置 | enable_unified_lockfile | lockfile 合一 | 布尔 | false | 默认为 false。若设置为 true，会将所有模块的 oh-package-lock.json5 文件整合进项目下的 oh-package-lock.json5。详情请见 enable_unified_lockfile。 |
| 其他设置 | enable_boost_extraction_speed | 文件解压提速 | 布尔 | false | 默认为 false。若设置为 true，在 ohpm 安装时，会使用更高效的文件解压方法，该功能当前处于实验阶段，详情请见 enable_boost_extraction_speed。 |
| 其他设置 | enable_lock_inner_pkg_version | 依赖内部的 .har 或 .tgz 依赖版本锁定 | 布尔 | true | 默认为 true。若设置为 false，在 ohpm 安装时，不会将依赖内部的 .har 或 .tgz 子依赖的版本保存至 oh-package-lock.json5，详情请见 enable_lock_inner_pkg_version。 |
| 其他设置 | case_sensitive_check | 路径大小写敏感检测 | 布尔 | false | 默认为 false。若设置为 true，在执行 ohpm 相关命令时，如果 ohpm 检测到工程中文件的配置路径和文件的实际路径存在大小写不一致问题时，则会报错提示开发者修改，详情请见 case_sensitive_check。该配置项仅在 Windows 环境下生效。 |
| 其他设置 | auto_skip_install | 依赖未发生变化时，自动跳过本次安装 | 布尔 | false | 默认为 false。若设置为 true，首次执行 ohpm install 安装命令后，如果用户未修改依赖再次执行 ohpm install 命令，则会跳过本次安装。详细跳过规则请见 auto_skip_install。 |
| 其他设置 | metadata_cache_effective | 设置元数据缓存的过期时间 | 数值 | 10080 | 默认缓存过期时间为 7 天，取值范围为 [1, 525600]，单位：分钟。该配置适用于 ~/.ohpm/cache/metadata 目录下所有先行版本元数据文件和全部版本元数据文件，以及工程目录下 .ohpm/lock/oh-install-meta.json5 中的先行版本元数据。说明：标准版本通常不会变更，故该参数在 ~/.ohpm/cache/metadata 目录下的标准版本元数据文件和工程目录下 .ohpm/lock/oh-install-meta.json5 中的标准版本元数据中不生效。 |
| 其他设置 | metadata_cache | 开启读取缓存的元数据文件 | 布尔 | false | 默认为 false。若设置为 true，在执行 ohpm install 命令时，会读取缓存的元数据文件（.ohpm/lock/oh-install-meta.json5 文件、~/.ohpm/cache/metadata 目录下文件），减少网络请求，缩短安装时间。详情请见 metadata_cache。 |
| 其他设置 | symlink_for_local_dep | 对本地 HAR 依赖解压后的路径，创建软链接 | 布尔 | false | 默认为 false。若设置为 true，在执行 ohpm install 过程中，对本地 HAR 依赖解压后的路径，创建软链接。详情见 symlink_for_local_dep。 |
CA 证书获取及配置
说明：CA 证书的获取需要区分系统：当从 Windows 系统浏览器下载的证书仅适用于 Windows 系统，当从 Mac 系统浏览器中获取的证书适用于 Mac 系统和 Linux 系统。
Windows 系统获取 CA 证书
依次访问以下证书下载地址，并根据下图操作下载 CA 证书到本地：
https://ohpm.openharmony.cn/
https://contentcenter-drcn.dbankcdn.cn/ //该域名用于文件资源下载，访问根路径仅可用于获取CA证书
访问 https://ohpm.openharmony.cn/ 地址，下载证书，请选择保存类型为证书链（访问 https://contentcenter-drcn.dbankcdn.cn/ 执行相同操作）。
通过访问 https://ohpm.openharmony.cn/ 地址获取证书 openharmony.cn.crt，通过访问 https://contentcenter-drcn.dbankcdn.cn/ 地址获取证书 update.hicloud.crt，在 .ohpmrc 文件中配置 ca_files=证书路径1，证书路径2（两个文件均需配置）。
ca_files=D:\_.openharmony.cn.crt,D:\update.hicloud.crt
Mac 系统获取 CA 证书
依次访问以下证书下载地址，并根据下图操作下载 CA 证书到本地：
https://ohpm.openharmony.cn/
https://contentcenter-drcn.dbankcdn.cn/ //该域名用于文件资源下载，访问根路径仅可用于获取CA证书
访问 https://ohpm.openharmony.cn/ 地址，下载证书，请选择保存类型为证书链（访问 https://contentcenter-drcn.dbankcdn.cn/ 执行相同操作）。
通过访问 https://ohpm.openharmony.cn/ 地址获取证书 openharmony.cn.pem，通过访问 https://contentcenter-drcn.dbankcdn.cn/ 地址获取证书 update.hicloud.pem，在 .ohpmrc 文件中配置 ca_files=证书路径1，证书路径2（两个文件均需配置）。
ca_file=/Users/用户名/_.openharmony.cn.pem,/Users/用户名/_.update.hicloud.pem
log_level
可设置 ohpm 日志输出级别，对应级别类型有 debug、info、warn、error，默认为：info。开发者在执行 ohpm 命令时，不同日志级别的区别和效果如下所示。
- debug：控制台会打印 debug、info、warn、error 日志。
- info：控制台会打印 info、warn、error 日志。
- warn：控制台会打印 warn、error 日志。
- error：控制台只会打印 error 日志。
install_all
在 ohpm 客户端 1.8.0 版本的 .ohpmrc 中支持 install_all 配置，用于控制 ohpm install，ohpm update，ohpm uninstall 的行为，install_all 在 .ohpmrc 文件中设置为 true 或缺省时：
- 使用
ohpm install命令时，将安装工程下所有模块的依赖，与使用ohpm install --all行为一致； - 使用
ohpm update时，将默认更新本模块下依赖并安装工程下所有模块的依赖，与使用ohpm update --all一致； - 使用
ohpm uninstall时，将默认删除本模块下依赖并安装工程下所有模块的依赖，与使用ohpm uninstall --all一致。
resolve_conflict
在 ohpm 客户端 1.5.0 版本开始支持依赖版本冲突自动解决功能。只需要在 .ohpmrc 文件中，将 resolve_conflict 配置为 true 或缺省，即可开启该功能。依赖冲突的处理策略为：当您的项目同时依赖了某个三方库的不同版本时，ohpm 将选择其中的最高版本进行安装。
注意：若某个三方库同时存在远程版本和本地版本（本地文件或源码依赖），无论本地版本的版本号是否大于远程版本，ohpm 的冲突处理策略都会优先选择本地版本作为待安装的版本。
模块内依赖版本冲突
如上图所示的依赖路径中，moduleA 为您正在开发的模块，其直接依赖为 B@1.1，C@1.1。其中 B@1.1 与 C@1.1 分别依赖了 D 的两个版本 D@1.2 与 D@1.3。当您开启了依赖版本冲突自动解决功能，ohpm 将会选择 D@1.3 版本作为待安装的版本，最终依赖路径被解析为下图蓝色箭头所指向的路径。
模块间依赖版本冲突
如上图所示的依赖路径中，moduleA、moduleB 为您同一项目下正在开发的两个模块，其中 moduleA 依赖 B@1.1，moduleB 依赖 C@1.1，B@1.1 与 C@1.1 分别依赖了 D 的两个版本 D@1.2 与 D@1.3。当您开启了依赖版本冲突自动解决功能，并且您是使用 ohpm install --all 进行安装时，ohpm 将会选择 D@1.3 版本作为待安装的版本，最终依赖路径被解析为下图蓝色箭头所指向的路径。
更新依赖版本的场景
当您希望将您某个模块的直接依赖更新成另一个版本，如下图所示，您手动将 C@1.1 更新为 C@1.2：
由于 C 更新为 C@1.2 后，不再依赖 D，若依赖 D 的版本在更新 C 版本之前已经通过 ohpm 的自动冲突处理机制锁定为 D@1.3 版本，此时 C 版本的升级将不会导致 D 的版本由 D@1.3 回退为 D@1.2，这样可以保证每一次更新都只是在上一次结果上进行影响最小的修改，最终的依赖路径将会被解析为下图蓝色箭头所指向的路径。
对于上述场景，如果希望 D 版本同时也回退至 D@1.2 版本，则需要在 ohpm install 之前执行 ohpm clean 命令清理各模块下的 oh-package-lock.json5 文件，以消除上一次安装结果的影响。
ohpm install 命令带 --target_path 选项时依赖冲突处理
target_path 下是 hvigor 在构建时根据目标产物 target 为各模块自动生成定制的依赖配置文件（oh-package.json5），详见 target_path。在生成的 oh-package.json5 中，依赖的版本部分可能包含 targetName，示例："version": "1.0.0+targetName"。
包含 targetName 信息的版本完整格式为：<major>.<minor>.<patch>[-<pre-release>][+<targetName>]，此时冲突处理规则如下：
<major>.<minor>.<patch>[-<pre-release>]部分的比较规则依然遵循上文各场景所描述的处理规则，即取版本号最大的依赖。- 当两个版本
<major>.<minor>.<patch>[-<pre-release>]部分一致时，取尾部有[+<targetName>]信息的依赖。
注意：
- 当两个版本尾部均有
[+<targetName>]信息，且 targetName 不一致时，会根据<target_path>/dependencyMap.json5中 targetName 是否为空进行区分处理。当 targetName 空时，打印警告提示。当 targetName 有值时，报错提示并中断程序。 - 当两个依赖中有一个是本地依赖时，优先取本地依赖；当两个依赖均是本地依赖时，获取本地依赖包内
oh-package.json5配置的 version 再次按照上述规则继续比较。
限制条件说明
- 若希望解决当前项目所有模块下的依赖版本冲突，请使用
ohpm install --all完成依赖安装。 - 若在执行
ohpm update或ohpm uninstall命令后，可能会破坏项目原有的依赖版本冲突处理结果。请额外执行一次ohpm install --all命令，重新处理当前项目所有模块下的依赖版本冲突。 - 当本地文件（
.har或.tgz后缀）依赖之间、本地源码模块依赖之间、本地文件（.har或.tgz后缀）依赖与本地源码模块依赖之间出现冲突时，ohpm 自动冲突处理机制会比较该依赖内部oh-package.json5文件中version字段配置的版本号大小，版本号大的将会被安装。
注意：如难以感知本地文件或本地源码依赖中的版本号，建议使用 overrides 来处理冲突。
resolve_conflict_strict
ohpm 客户端从 5.0.9 版本，开始支持严格的依赖版本冲突处理机制。在 .ohpmrc 文件中，将 resolve_conflict_strict 配置为 true 开启该功能。
严格模式下，当您的项目同时依赖了某个三方库的不同版本时，ohpm 将按照严格模式冲突决策算法决策出最符合要求的版本进行安装，当程序不能决策出符合要求的版本时将报错。
严格模式冲突决策算法
- 同一依赖，存在一个固定版本（如：1.0.1）、多个范围版本（如：
^1.0.0、~1.1.0、>1.0.0等）时，如果该固定版本在所有范围版本交集区间内，则最终安装该固定版本，否则冲突决策失败； - 同一依赖，仅存在多个范围版本时，如果所有范围版本存在交集，则最终安装仓库中存在且在交集区间内的最高版本；若所有范围版本不存在交集区间，则冲突决策失败；
- 使用同一本地依赖（如：
./a.har），依赖存放路径不一致时，冲突决策失败； - 同一依赖，同时存在本地版本（如：
./a.har）与远程版本（如：^1.0.0）时，冲突决策失败； - 同一依赖，存在多个固定版本时，冲突决策失败。
注意：严格模式下，依赖冲突决策成功时，ohpm 会打印被解决冲突的依赖的警告信息，包含：依赖名称、所有冲突的版本、最终安装版本、受影响的模块列表。严格模式下，依赖冲突决策失败时，ohpm 会打印依赖冲突树并在树上高亮显示解决失败的依赖及版本和所有解决失败的依赖的错误信息，包含：依赖名称、所有冲突的版本。当依赖存在版本冲突时，可以通过 overrides 配置解决。
示例
将 resolve_conflict_strict 开关设置为 true：
ohpm config set resolve_conflict_strict true
在 AppTest3 工程根目录的 oh-package.json5 中配置依赖 @ohos/axios：
{
"modelVersion": "6.1.1",
"description": "Please describe the basic information.",
"dependencies": {
"@ohos/axios": "2.2.5"
}
}
在 AppTest3 工程下 entry 模块的 oh-package.json5 中配置依赖 @ohos/axios：
{
"name": "entry",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "",
"author": "",
"license": "",
"dependencies": {
"@ohos/axios": "2.2.6"
}
}
在 AppTest3 工程下任意目录执行命令：ohpm install --all，根据严格的依赖版本冲突处理规则，此时 ohpm 会安装失败并打印依赖冲突树，如下所示：
crypto_path
ohpm 客户端从 5.2.0 版本开始，支持对敏感配置项进行加密存储和读取。
支持加密的敏感配置项：
| 配置项 | 说明 | 示例格式 |
|---|---|---|
| key_passphrase | 必须加密，对应 key_path 的私钥密码 | key_passphrase=security:xxx |
| http_proxy | 代理用户名密码部分可加密（username:password 替换为密文） | http_proxy=http://security:xxx@proxy:port |
| https_proxy | 代理用户名密码部分可加密（username:password 替换为密文） | https_proxy=https://security:xxx@proxy:port |
| AccessToken | 仓库认证配置（:_auth 和 :_read_auth） | //<仓库地址>/:_auth=security:xxx、//<仓库地址>/:_read_auth=security:xxx |
用户可通过以下流程实现配置加密：
使用 ohpm config encrypt 命令生成加密组件并对标准输入的数据加密。
在 .ohpmrc 文件中配置 crypto_path 加密组件路径和敏感配置项。
crypto_path=D:\path\to\crypto_dir
key_passphrase=security:xxx
http_proxy=http://security:xxx@proxy:port
https_proxy=https://security:xxx@proxy:port
//<仓库地址>/:_auth=security:xxx
//<仓库地址>/:_read_auth=security:xxx
说明：
key_passphrase配置项必须使用密文格式配置，其余敏感配置项仍兼容明文配置。- 命令执行时，根据优先级（项目级 > 用户级
.ohpmrc）获取命令所需的敏感配置项后，使用该配置项同层级的crypto_path指定的加密组件进行解密。
key_passphrase
ohpm 客户端从 5.2.0 版本开始，支持在 .ohpmrc 文件中配置 key_passphrase 私钥密码，用于自动解密 key_path 对应的私钥文件。
执行 ohpm publish、ohpm unpublish 等需要认证的命令时，系统会自动使用 key_passphrase 解密私钥，无需手动输入密码。
key_passphrase必须是通过ohpm config encrypt命令生成的密文。- 需同时配置
key_path私钥文件路径。 - 需同时配置
crypto_path加密组件路径，用于运行时解密key_passphrase。
示例：
在项目级或用户级 .ohpmrc 文件中配置，执行 publish 命令，用户无需手动输入密码即可完成推包操作。
key_path=:\path\to\key_file
crypto_path=D:\path\to\crypto_dir
key_passphrase=security:xxx
AccessToken
AccessToken 是 ohpm-repo 2.1.0 版本新引入的认证机制，用户通过 ohpm-repo 界面生成 Token，并将其配置至 ohpm 客户端配置文件中。
在与 ohpm-repo 交互时，客户端会自动附带 Token 进行身份验证。该 Token 分两种权限等级：
- 只读 Token 允许执行 info 和 install 操作；
- 读写 Token 除了包含只读权限外，还支持 publish 和 unpublish 操作。
每位用户每种权限类型的 Token 最多可生成 10 个，首次生成时系统自动复制到剪贴板，后续不再显示完整 Token 内容。
如何获取 AccessToken
当前 AccessToken 仅 ohpm-repo 支持，登录成功后，在 ohpm-repo 首页的右上角 > 认证管理 > AccessToken 页面进行生成。
如何配置 AccessToken
在 .ohpmrc 文件配置示例如下：
//127.0.0.1:8088/repos/ohpm/:_auth=readWriteToken
//127.0.0.1:8088/repos/ohpm/:_read_auth=readOnlyToken
其中：
//127.0.0.1:8088/repos/ohpm/是 ohpm-repo 的 registry 地址去除协议名的部分；:_auth和:_read_auth分别代表配置为读写 Token 或只读 Token，readWriteToken和readOnlyToken代表 Token 具体的值。ohpm 客户端执行 info、install 操作会优先使用只读 Token，如果只读 Token 不存在才会使用读写 Token。ohpm 客户端执行 publish、unpublish 操作时只会使用读写 Token。每种 Token 最多配置三条。
enforce_dependency_key
ohpm 从 1.7.0 版本开始，支持在 .ohpmrc 文件中配置 enforce_dependency_key，该配置项值为布尔类型，默认为 false。将配置设置为 true 后，ohpm 会校验各模块的 oh-package.json5 中配置的直接依赖中的本地依赖名称与其对应的包名（模块名）是否一致，若不一致会导致依赖安装失败并在错误日志中打印出不一致的依赖名称与其对应的包名（模块名）。
示例：
在 MyApplication 工程下存在一个名称为 foo 的模块，foo 模块的 oh-package.json5 如下所示：
{
"name": "foo",
"version": "2.0.0",
"description": "Please describe the basic information.",
}
在 MyApplication 工程下存在另一个名称为 bar 的模块，且 bar 模块中依赖了 foo 模块，bar 模块的 oh-package.json5 如下所示：
{
"name": "bar",
"version": "1.0.0",
"description": "Please describe the basic information.",
"dependencies": {
"fee": "file:../foo"
},
}
如上所示，bar 模块的 oh-package.json5 中配置了对 foo 模块的依赖，并为 foo 模块起了一个别名为 fee。当在 .ohpmrc 中将 enforce_dependency_key 配置为 true 时：
enforce_dependency_key=true
此时在 MyApplication 下执行 ohpm install --all 命令将打印如下错误日志，同时会中断命令的执行：
ohpm ERROR: local dependency "fee" found in "D:\DevecostudioProjects\MyApplication2\bar\oh-package.json5" does not match the actual name "foo" of its oh-package.json5
ohpm ERROR: Install failed, detail: There are some dependency names that are inconsistent with the actual package names.
若没有配置 enforce_dependency_key 或将其配置为 false 时，命令将不会被中断，同时上述错误日志的日志级别将会下调为告警日志：
ohpm WARN: local dependency "fee" found in "D:\DevecostudioProjects\MyApplication2\bar\oh-package.json5" does not match the actual name "foo" of its oh-package.json5
建议在 .ohpmrc 文件中配置 enforce_dependency_key 为 true，禁止以别名的方式配置本地依赖，避免出现如下场景：
基于上述示例，在 MyApplication 下真的存在一个名称为 fee 的模块，且该模块的版本号小于 foo 模块，fee 模块的 oh-package.json5 如下所示：
{
"name": "fee",
"version": "1.0.0", // 小于foo的版本号2.0.0
"description": "Please describe the basic information.",
}
且 entry 模块中同时依赖了 fee 与 bar，entry 模块的 oh-package.json5 依赖配置如下所示：
{
"name": "entry",
"version": "1.0.0",
"dependencies": {
"fee": "file:../fee",
"bar": "file:../bar"
},
}
此时在 entry 的依赖树中，依赖 fee 存在两个版本：一个别名为 fee 的 foo 模块，一个名称为 fee 的 fee 模块，若此时开启了 resolve_conflict，由于 fee 模块的实际版本号为 1.0.0 要小于 foo 模块的版本号 2.0.0，在执行 ohpm install 时将只会在 entry 模块的 oh_modules 下安装以 fee 为别名的 foo 模块，而实际的 fee 模块则不会被安装。
在 entry 的 oh_modules 下会生成一个名称为 fee 的软链接，该链接却指向 foo 模块的实际路径：
如果 entry 实际希望依赖的是真实的 fee 模块而不是 foo 模块，则此时会导致 entry 无法编译成功。
注意：
- 从 ohpm 客户端 5.0.7 开始，若项目级
build-profile.json5文件中strictMode字段下配置了useNormalizedOHMUrl开关且useNormalizedOHMUrl=true，则该配置优先级高于enforce_dependency_key，如果 ohpm 检测到依赖别名与oh-package.json5中 name 不一致时，会报错提示并中止程序执行；若未配置useNormalizedOHMUrl或useNormalizedOHMUrl=false时，是否校验别名一致性则根据enforce_dependency_key配置决定。 - 项目级
build-profile.json5文件中，products 节点下任意 product 字段配置了useNormalizedOHMUrl=true，则 ohpm 中useNormalizedOHMUrl开关会被设置为 true，即 ohpm 检测到项目中依赖别名与oh-package.json5中 name 不一致时，会报错提示并中止程序执行。
ensure_dependency_include
ohpm 从 1.7.0 版本开始，支持在 .ohpmrc 文件中配置 ensure_dependency_include，该配置项值为布尔类型，默认为 false。
在 ohpm prepublish/publish 时，ohpm 会扫描待发布包的内容，如果代码中 import 了某个包的内容，但相应的包没有配置在 dependencies/dynamicDependencies 中，即如果该配置项的值为 true，则 ohpm 会打印错误信息并中断执行；否则，ohpm 只会打印告警提示。
例如，test.har 包的代码中 import 了 @ohos/hypium 包，但 test.har 的 oh-package.json5 的 dependencies 中未配置 @ohos/hypium 依赖。下面就 ensure_dependency_include 开关为 true/false 时 ohpm publish 的行为进行举例说明。
示例 1
将 ensure_dependency_include 开关置为 false：
ohpm config set ensure_dependency_include false
发布 test.har 包。
ohpm publish test.har
当 ensure_dependency_include=false 时，发布完成后将打印告警提示。
示例 2
将 ensure_dependency_include 开关置为 true：
ohpm config set ensure_dependency_include true
发布 test.har 包。
ohpm publish test.har
当 ensure_dependency_include=true 时，发布时将报错。
disallow_nested_package
ohpm 从 1.8.0 版本开始，支持在 .ohpmrc 文件中配置 disallow_nested_package，该配置项值为布尔类型，默认为 false。在 ohpm prepublish/publish 时，ohpm 会扫描待发布包的 dependencies 和 dynamicDependencies 依赖配置，如果依赖配置中存在相对路径或绝对路径配置的 .har、.tgz 依赖且 disallow_nested_package 开关为 true，则 ohpm 会报错提示。
示例：
lib_nested.har 包的 dependencies 中配置了如下依赖：
{
"dependencies": {
"liblib_nested.so": "file:./src/main/cpp/types/liblib_nested",
"hsp": "./libs/hsp-default.tgz",
"lib_har": "./libs/lib_har.har"
}
}
将 disallow_nested_package 开关置为 true。
ohpm config set disallow_nested_package true
发布 lib_nested.har。
ohpm publish lib_nested.har
当 disallow_nested_package=true 时，发布时将报错。
odm_r2_project_root
odm_r2_project_root 是 ohpm 客户端 1.8.0 新增的开关配置，默认为 false，可以通过 config 命令或直接在 .ohpmrc 文件中修改其值。
当该配置为 true 时，若在 overrideDependencyMap 中配置的依赖项替换文件中存在以相对路径配置的本地依赖项时，在 ohpm 运行时会基于工程根路径来查找这些本地依赖项。
示例：
.ohpmrc 中开启 odm_r2_project_root：
odm_r2_project_root=true
overrideDependencyMap 配置示例：
在工程根目录下的 oh_package.json5 中增加 overrideDependencyMap 配置，如下：
{
"overrideDependencyMap": {
"lib1": "lib1-override-dep-map.json5",
"lib2": "lib2-override-dep-map.json5"
}
}
依赖项 "lib1" 的依赖项替换文件 lib1-override-dep-map.json5 示例：
{
"dependencies": {
"@ohos/test": "file:./test.har"
}
}
如上第 3 步所示，当 odm_r2_project_root 开关设置为 true 时，在 ohpm 运行时会以工程根目录为起点查找 "./test.har"，比如：工程根路径为：D:\path\to\MyProject，在 ohpm 运行时解析得到 test.har 的绝对路径为：D:\path\to\MyProject\test.har。
compability_log_level
ohpm 客户端从 5.0.1 开始新增开关配置 compability_log_level 字段，用于控制在缺少兼容性检测需要的字段时 ohpm 的处理逻辑。
compability_log_level 字段默认赋值为 'warn'，可配置的日志等级请见开关配置项说明。
在执行 prepublish、publish 命令时，ohpm 会检测 oh-package.json5 文件中是否配置了兼容性检测需要的所有字段（compatibleSdkVersion, compatibleSdkType, obfuscated, nativeComponents），详见模块级 oh-package.json5 字段说明，下面统称 '兼容性字段'，如果未配置，则会根据日志等级打印提示或报错。
开关配置项说明
close：关闭功能，不主动检测兼容性字段。info：检测到未配置的兼容性字段时，打印 info 日志。warn：检测到未配置的兼容性字段时，打印警告日志。error：检测到未配置的兼容性字段时，打印报错提示并中断程序。
enable_unified_lockfile
ohpm 客户端从 5.1.1 开始新增开关配置 enable_unified_lockfile 字段。启用此特性后，ohpm 将自动整合项目中所有子模块的 oh-package-lock.json5 文件，统一生成至项目根目录的 oh-package-lock.json5 文件中。
启用 enable_unified_lockfile=true 后，项目级统一管理 lockfile 锁文件，针对模块间存在重复依赖的场景，显著减少 ohpm install 耗时，优化构建流程。
注意：启用 enable_unified_lockfile=true 后，原分散在各模块下的 .hsp 依赖安装目录将统一迁移至项目根目录。在流水线上开启此特性时，需搭配配套的 hvigor 使用。
enable_boost_extraction_speed
ohpm 客户端从 5.3.0 开始新增开关配置 enable_boost_extraction_speed 字段。ohpm 安装时涉及对 .har/.tgz 三方包文件的解压和遍历，启用此特性后，将使用高性能方法进行解压和遍历，当工程中存在大文件依赖时，可以显著减少 ohpm install 耗时。该功能当前处于实验阶段，暂不支持解压包含软链接的三方包文件。
enable_lock_inner_pkg_version
ohpm 客户端从 5.3.1 开始新增开关配置 enable_lock_inner_pkg_version 字段。默认为 true，若设置为 false，在 ohpm 安装时，不会将依赖内部的 .har 或 .tgz 子依赖的版本保存至 oh-package-lock.json5，以防 oh-package-lock.json5 中保存不存在的路径导致二次安装报错。
如下图所示，蓝色箭头标识最终要安装的依赖，安装的依赖 D@1.0.0 来自依赖 B@1.0.0（依赖名称和依赖版本相同的依赖会被定性为相同依赖，最终安装哪个由依赖构建先后顺序决定），因 B@1.0.0 并没有安装，但 oh-package-lock.json5 中锁定了依赖 D 的版本，在二次安装时会爆出 D 的依赖路径不存在错误，此时需要将该开关设置为 false。
oh-package-lock.json5 示例
生成 library.har，oh-package.json5 如下。
{
"name": "library",
"version": "1.0.0",
"description": "Please describe the basic information.",
"author": "",
"license": "Apache-2.0",
"dependencies": {
"inner": "./libs/inner.har"
},
"types": "Index.d.ets",
"artifactType": "obfuscation",
"compatibleSdkVersion": 21,
"compatibleSdkType": "HarmonyOS",
"obfuscated": false
}
entry 依赖 library.har，oh-package.json5 如下。
{
"name": "entry",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "",
"author": "",
"license": "",
"dependencies": {
"library": "./library.har"
}
}
.ohpmrc 中配置开关：enable_lock_inner_pkg_version=false，工程任意目录下执行命令：ohpm install --all，此时生成的 entry/oh-package-lock.json5 中不会锁定内部包 inner 的版本，如下所示。
{
"specifiers": {
"library@library.har": "library@library.har"
},
"packages": {
"library@library.har": {
"name": "library",
"version": "1.0.0",
"resolved": "library.har",
"registryType": "local",
"dependencies": {
"inner": "./libs/inner.har"
}
}
}
}
enable_lock_inner_pkg_version=true 时，entry/oh-package-lock.json5 结果如下：
{
"specifiers": {
"inner@../oh_modules/.ohpm/library@85ursk4cfzbgycewlyxweed+cyyeeixxig5mlazoo+g=/oh_modules/library/libs/inner.har": "
inner@../oh_modules/.ohpm/library@c0jkxsxl3amvdd7rr1enrkrejzharxwucdoyc29br+u=/oh_modules/library/libs/inner.har",
"library@library.har": "library@library.har"
},
"packages": {
"
inner@../oh_modules/.ohpm/library@c0jkxsxl3amvdd7rr1enrkrejzharxwucdoyc29br+u=/oh_modules/library/libs/inner.har
": {
"name": "inner",
"version": "1.0.0",
"resolved": "../oh_modules/.ohpm/library@c0jkxsxl3amvdd7rr1enrkrejzharxwucdoyc29br+u=/oh_modules/library/libs/inner.har"
"registryType": "local"
},
"library@library.har": {
"name": "library",
"version": "1.0.0",
"resolved": "library.har"
"registryType": "local",
"dependencies": {
"inner": "./libs/inner.har"
}
}
}
}
case_sensitive_check
ohpm 客户端从 6.21.0 新增开关配置 "case_sensitive_check" 字段。若设置为 true，在执行 ohpm 相关命令时，如果 ohpm 检测到工程中文件的配置路径和文件的实际路径存在大小写不一致问题时，则会报错提示开发者修改。该配置项仅在 Windows 环境下生效。
检测范围：
.har包、.tgz包、工程中的 module 作为依赖时的路径。prefix、target_path、parameterFile的命令中配置的目录或路径。overrides配置项中的本地依赖路径，overrideDependencyMap配置项涉及的配置文件及文件内的本地依赖路径，parameterFile配置文件及文件内的本地依赖路径。
示例：
准备本地 har 包：test.har，该 har 包内 oh-package.json5 中 name 为：test，将其放置在模块 entry 的 libs 目录下。
entry 依赖 test.har，则原始依赖路径为：<project_dir>/entry/libs/test.har，entry 的 oh-package.json5 内容如下：
{
"name": "entry",
"version": "1.0.0",
"description": "Please describe the basic information.",
"dependencies": {
"test": "./Libs/test.har"
}
}
执行 ohpm install，ohpm 可检测到 test.har 的实际路径（<project_dir>/entry/libs/test.har）与配置路径（<project_dir>/entry/Libs/test.har）大小写不一致（配置时 libs 目录名存在大写字母：'L'，与原始目录名不一致），此时 ohpm 会报错提示并中断执行。
auto_skip_install
ohpm 客户端从 26.0.0.410 新增开关配置 auto_skip_install 字段，该配置项值为布尔类型，默认为 false。设置为 true 时，首次执行 ohpm install 安装命令后，再次执行 ohpm install 命令时会检测依赖是否发生变化，若依赖未发生变化则跳过本次安装。
检测范围：
工程级或者模块级的 oh-package.json5 中的依赖，相关参数包括：
- 工程级和模块的
dependencies、devDependencies、dynamicDependencies的参数。 - 工程级
overrides、parameterFile、overrideDependencyMap的参数。 hvigorfile.ts文件中定义的动态依赖，更多可参考修改oh-package.json5中的依赖。
.ohpmrc 配置文件中的相关参数，包括：
install_allresolve_conflictresolve_conflict_strictenforce_dependency_keyodm_r2_project_rootenable_unified_lockfilecase_sensitive_check
工程级目录下的 oh_modules 下包目录是否完整。
示例：
创建一个鸿蒙工程，将 .ohpmrc 中的 auto_skip_install 设置为 true，模块级 entry 中 oh-package.json5 示例：
{
"name": "entry",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "",
"author": "",
"license": "",
"dependencies": {
"test": "1.0.0"
}
}
执行 ohpm install 命令后，不修改工程依赖配置再次执行 ohpm install 命令，由于版本依赖未发生变化，第二次安装会有跳过安装的提示：
ohpm WARN: project dependency not change，skip install
install completed in 0s 29ms
修改工程级 oh-package.json5，添加 parameterFile 和 overrides 信息如下所示：
{
"modelVersion": "26.0.0",
"description": "Please describe the basic information.",
"parameterFile": "./parameterFile.json",
"overrides": {
"test": "@param:dependencies.test"
}
}
新增 parameterFile.json 内容如下所示：
{
"version": "1.0.0",
"dependencies": {
"test": "1.0.1"
}
}
执行 ohpm install 命令，由于依赖发生变化，这次会提示哪些指纹信息发生变化，不会有跳过安装的日志：
ohpm WARN: fingerprint rootNodesFingerprint changed
ohpm WARN: fingerprint old: 34f4ab8795166b45c388b44803b3bb44
ohpm WARN: fingerprint new: 68fea7ec8dd32e6375b52ef44a0914ef
ohpm INFO: MetaDataFetcher fetching meta info of package 'test' from https://ohpm.openharmony.cn/ohpm/
ohpm INFO: fetch meta info of package 'test' success https://ohpm.openharmony.cn/ohpm/test
ohpm INFO: fetch package done 1 test from https://ohpm.openharmony.cn/ohpm/test/-/test-1.0.1.har
install completed in 1s 217ms
metadata_cache
ohpm 客户端从 26.0.0.410 版本新增开关配置 metadata_cache 字段，该配置项值为布尔类型，默认为 false。若设置 metadata_cache 为 false，执行 ohpm install 时，仅加载 oh-package-lock.json5 文件中缓存的元数据。若设置 metadata_cache 为 true，执行 ohpm install 时，将按照如下优先级加载缓存的元数据：oh-package-lock.json5 文件 > oh-install-meta.json5 文件 > ~/.ohpm/cache/metadata/。
开启 metadata_cache 开关，执行 ohpm install 后会生成 oh-install-meta.json5 文件和元数据缓存文件，存放位置如下：
生成的 oh-install-meta.json5 文件，放置在当前工程下的 .ohpm/lock 目录内。
~/project
.ohpm/
lock/
oh-install-meta.json // 项目中所有oh-package-lock.json5文件中packages对象内远程包的集合镜像
生成的元数据缓存文件，放置在缓存路径 ~/.ohpm/cache/metadata，按 group 名称和包名呈现。
~/.ohpm/cache/
metadata/
group/
packagenameA/
-- all.json // 全部元数据
-- xx.json // 固定版本的元数据，xx为版本号
packagenameB/
-- xx.json // 固定版本的元数据
packagenameC/
-- all.json // 全部元数据
-- xx.json // 固定版本的元数据
说明：启用 metadata_cache 设置为 true，当 oh-package.json5 中配置范围版本，且范围版本中有新版本发布时，ohpm 可能从本地缓存的元数据中读取结果，而非发起网络请求。这可能导致无法获取新的包版本。这时需要执行 ohpm cache clean @group/package 命令清除对应包的元数据缓存文件，或执行 ohpm cache clean 命令清除所有元数据缓存文件。清除命令请参考 ohpm cache clean。
symlink_for_local_dep
ohpm 客户端从 26.0.0.630 版本新增开关配置 symlink_for_local_dep 字段，该配置项值为布尔类型，默认为 false。若设置 symlink_for_local_dep 为 true，执行 ohpm install 过程中，对本地 HAR 依赖解压后的路径创建软链接，放置在工程目录 /oh_modules/.ohpm/oh_modules 中。
本地 HAR 依赖配置示例：
{
"modelVersion": "6.1.0",
"description": "Please describe the basic information.",
"dependencies": {
"library5": "file:./library5.har"
}
}
创建的软链接如下：
oh-package.json5
从 OHPM 5.0.0 版本开始，支持区分工程级与模块级 oh-package.json5 配置。其中：
- 工程级
oh-package.json5文件：位于工程根目录下，主要用来描述全局配置，如：依赖覆盖（overrides）、依赖关系重写（overrideDependencyMap）和参数化配置（parameterFile）等，详情请见：工程级oh-package.json5字段说明； - 模块级
oh-package.json5文件：位于工程各个模块的根目录下，用来描述包名、版本、入口文件（类型声明文件）和依赖项等信息，详情请见：模块级oh-package.json5字段说明。
开发者可将标准的 DevEco Studio 工程下的各个模块打成 HAR 包后，发布到 OpenHarmony 三方库中心仓；所有发布到仓库的包必须包含模块级 oh-package.json5 文件，以描述当前包基本信息。
工程级 oh-package.json5 字段说明
| 配置项 | 字段名称 | 字段说明 | 字段要求 | 字段类型 | 默认值 | 备注 |
|---|---|---|---|---|---|---|
| 开发态版本 | modelVersion | 开发态版本号 | 必选 | 字符串 | 无 | 开发态版本号。默认版本号为 DevEco Studio 配套的 modelVersion，以 DevEco Studio 6.1.1 Release 为例，配套的 modelVersion 为 "6.1.1"。如需修改 modelVersion，修改后的值不能小于 5.0.0，且不能大于 DevEco Studio 配套的 modelVersion。 |
| 描述配置 | description | 简介 | 可选 | 字符串 | 无 | 用于描述工程信息的字符串。 |
| 依赖配置 | dependencies | 生产依赖 | 可选 | 对象 | {} | 用于配置参与编译/运行阶段使用的依赖，声明需要在代码中 import 的三方库（不建议在工程级 oh-package.json5 中配置生产依赖）。 |
| 依赖配置 | devDependencies | 开发依赖 | 可选 | 对象 | {} | 配置开发态依赖，配置只能参与项目的开发或测试阶段的依赖。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（如手机）上使用，则不能在其中配置。 |
| 依赖配置 | dynamicDependencies | 动态依赖 | 可选 | 对象 | {} | 配置项目动态依赖的 HSP 模块。在开发者需要动态加载 HSP 的时候配置使用（不建议在工程级 oh-package.json5 中配置动态依赖）。 |
| 依赖配置 | overrides | 依赖覆盖配置 | 可选 | 对象 | {} | 支持将依赖树中的包替换为另一个指定版本，详情见 overrides。 |
| 依赖配置 | overrideDependencyMap | 重写依赖关系 | 可选 | 对象 | {} | 支持将依赖树中包的子依赖替换为配置文件中配置的依赖，详情见 overrideDependencyMap。 |
| 依赖配置 | exclusions | 第三方依赖的子依赖排除配置 | 可选 | 对象 | {} | 支持移除第三方依赖（远程依赖、本地文件依赖）中的一个或多个子依赖，详情见 exclusions。 |
| 其他 | scripts | 自定义脚本 | 可选 | 对象 | {} | 维护一个脚本别名到脚本内容的映射表，开发者可以通过 ohpm run <脚本别名> 来触发对应脚本内容的执行。 |
| 其他 | hooks | 钩子 | 可选 | 对象 | {} | 安装或卸载的钩子设置，包含 "preInstall"，"postInstall"，"preUninstall"，"postUninstall"，"preVersion"，"postVersion"，"prePublish"，"postPublish" 字段。仅支持执行当前工程中的 hooks，不支持执行依赖中的 hooks。 |
| 其他 | parameterFile | 参数化配置文件路径 | 可选 | 字符串 | 无 | 标识是否开启参数化。未配置：关闭参数化；已配置：开启参数化。需同时指定参数化配置文件路径，详情见 parameterFile。 |
| 其他 | properties | 多环境依赖管理参数 | 可选 | 对象 | {} | 该配置参数用于多环境下的依赖管理。开发者通过 parameterFile 完成依赖配置后，在 parameterFile 字段中使用 properties 参数，详情见 properties。说明：如 debug 和 beta 环境下需要配置不同的 parameterFile，实现不同的包依赖管理，诸如此类场景称为多环境。 |
注意：不建议在工程级依赖中配置非 devDependencies 的依赖，即一个 Hsp/Har 模块的非开发态依赖都要在相应模块的 dependencies 和 dynamicDependencies 中声明。
模块级 oh-package.json5 字段说明
模块级 oh-package.json5 文件位于工程各个模块的根目录下，用来描述当前模块被其他模块依赖时的相关信息，包括：作为依赖时的依赖名（name）、作为依赖时的版本号（version）、入口文件（main/types）和子依赖项等信息。
| 配置项 | 字段名称 | 字段说明 | 字段要求 | 字段类型 | 默认值 | 备注 |
|---|---|---|---|---|---|---|
| 描述配置 | name | 名称 | 必选 | 字符串 | 无 | 该模块作为依赖时的依赖名，用于唯一标识该依赖。格式为：@group/packagename 或 packagename，长度：[1, 128]，全局唯一，即一个应用中，不同依赖的依赖名不能重复。建议 name 命名时包含组织名称 group，便于管理和识别三方依赖。name 中只有在存在组织名称 group 时，才能有且仅能有一个 '@' 符号，有且仅有一个路径分隔符 '/'。组织名称 group 格式：1、仅允许以小写字母开头，可由小写字母、数字、中划线（-）、下划线（）组成。2、禁止以中划线（-）、下划线（）结尾。3、不允许为 ArkTS 的保留关键字。packagename 格式：1、仅允许以小写字母开头，可由小写字母、数字、点（.）、中划线（-）、下划线（）组成。2、禁止以点（.）、中划线（-）、下划线（）结尾。3、不允许为 ArkTS 的保留关键字。 |
| 描述配置 | version | 版本号 | 必选 | 字符串 | 1.0.0 | 该模块构建产物（HAR/HSP）的版本号。规范：采用 X.Y.Z（主版本.次版本.修订号）三段式结构，遵循 semver 语义化规范，从 1.0.0 开始。 |
| 描述配置 | description | 简介 | 可选 | 字符串 | 无 | 用于描述该模块构建产物（HAR/HSP）的信息，有助于被搜索发现。长度范围为 0-512 字符。 |
| 描述配置 | keywords | 关键字 | 可选 | 数组 | [] | 关键字信息数组，便于搜索使用。例如：["tools", "project"]。 |
| 描述配置 | author | 作者 | 可选/必选 | 对象或字符串 | 无 | author 包含 name 字段（必选）、email 字段（可选）、url 字段（可选），可通过格式对象或字符串格式配置。name 字段允许使用字母、数字，点（.），中划线（-），下划线（_），空格，中文，长度范围为 [1,128]，email 长度范围为 [1,64]，url 长度范围为 [1,256]。对象格式："author": {"name": "xxx" , "email": "***@example.com" , "url": "https://xxx.com" }。字符串格式："author": "name<***@example.com>(https://xxx.com)"。仅发布到 OpenHarmony 三方库中心仓时，必须填写，其他场景可选填。 |
| 描述配置 | homepage | 主页链接 | 可选 | 字符串 | "" | 通常是项目 gitee 链接。 |
| 描述配置 | repository | 仓库地址 | 可选 | 字符串 | "" | 开源代码仓库地址。在私仓管理界面的系统设置处可定义是否为必填。 |
| 描述配置 | license | 开源协议 | 可选/必选 | 字符串 | "ISC" | 当前项目的开源许可证。遵循 spdx license 规范。许可证若为 GPL，repository 建议不为空。仅发布开源三方库到 OpenHarmony 三方库中心仓时，必须填写，其他场景可选填。 |
| 依赖配置 | dependencies | 生产依赖 | 可选 | 对象 | {} | 用于配置参与编译/运行阶段使用的依赖，声明需要在代码中 import 的三方库（参与编译/运行阶段使用的依赖）。 |
| 依赖配置 | devDependencies | 开发依赖 | 可选 | 对象 | {} | 用于配置开发态依赖，只能参与项目的开发或测试阶段。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（手机）上使用，则不能在其中配置。通过 devDependencies 引入的依赖，不校验循环依赖。 |
| 依赖配置 | dynamicDependencies | 动态依赖 | 可选 | 对象 | {} | 用于配置项目动态依赖的 HSP 模块。在开发者需要动态加载 HSP 的时候配置使用。 |
| 文件配置 | main | 入口 | 必选 | 字符串 | 无 | 指定加载的入口文件。 |
| 文件配置 | types | 类型定义 | 可选 | 字符串 | "" | 指定类型定义的文件名。当用 typescript 定义新的类型，需要提供给其他开发者使用，则需要指定其声明文件，一般为 .d.ts，.d.ets 文件。 |
| 文件配置 | oh-exports | 控制导出模块 | 可选 | 对象 | {} | 通过 oh-exports 字段控制导出模块中文件，实现包的可见性控制。支持导出目录文件（导出时不校验文件，全量导出目录内容）和特定后缀文件（ets/ts/js）。详情见 oh-exports 配置示例。 |
| 兼容性检测相关配置 | compatibleSdkVersion | SDK 版本 | 可选 | 字符串 | 无 | 三方库开发者使用的 SDK 版本，构建时由 Hvigor 自动填充，提供给 SDK 做兼容性检测。在 prepublish、publish 时，ohpm 会对该字段进行检测（非空和长度校验），并根据 .ohpmrc 中开关 compability_log_level 配置的值进行提示或报错处理。详情见兼容性字段配置示例。 |
| 兼容性检测相关配置 | compatibleSdkType | SDK 类型 | 可选 | 字符串 | 无 | 三方库开发者使用的 SDK 类型，构建时由 Hvigor 自动填充，提供给 SDK 做兼容性检测，示例值："OpenHarmony"、"HarmonyOS"。在 prepublish、publish 时，ohpm 会对该字段进行检测（非空和长度校验），并根据 .ohpmrc 中开关 compability_log_level 配置的值进行提示或报错处理。详情见兼容性字段配置示例。 |
| 兼容性检测相关配置 | obfuscated | 混淆标识 | 可选 | 布尔 | 无 | 三方库是否开启混淆标识，构建时由 Hvigor 自动填充，提供给 SDK 做兼容性检测。在 prepublish、publish 时，ohpm 会对该字段进行检测（非空校验），并根据 .ohpmrc 中开关 compability_log_level 配置的值进行提示或报错处理。详情见兼容性字段配置示例。 |
| 兼容性检测相关配置 | nativeComponents | native so 依赖配置 | 可选 | 数组 | 无 | 三方库使用的 so 包配置，构建时由 Hvigor 自动填充，提供给 SDK 做兼容性检测。对于用户自行引入的 so 依赖（存放于 libs 目录），需要用户手动维护该数组，数组单个元素类型为对象，对象内可配置的字段有：name、compatibleSdkVersion、compatibleSdkType。在 prepublish、publish 时，如果包内存在 so 包，则 ohpm 会对该字段进行检测，并根据 .ohpmrc 中开关 compability_log_level 配置的值进行提示或报错处理；反之则不检测该字段。详情见兼容性字段配置示例。 |
| 其他 | artifactType | 类型 | 可选 | 字符串 | "original" | OpenHarmony 包制品类型，有两个选项：original、obfuscation。original：源码，即发布源码（.ts/.ets）；obfuscation：混淆代码，即源码经过混淆之后发布上传。 |
| 其他 | scripts | 自定义脚本 | 可选 | 对象 | {} | 维护一个脚本别名到脚本内容的映射表，开发者可以通过 ohpm run <脚本别名> 来触发对应脚本内容的执行。 |
| 其他 | hooks | 钩子 | 可选 | 对象 | {} | 安装或卸载的钩子设置，包含 "preInstall", "postInstall", "preUninstall", "postUninstall", "preVersion", "postVersion", "prePublish", "postPublish" 字段。仅支持执行当前工程中的 hooks，不支持执行依赖中的 hooks。 |
| 其他 | category | 检查规则白名单 | 可选 | 字符串 | {} | 在私仓管理界面配置后自动生成，白名单为分号隔开的字符串列表，每个列表项必须是一个由大小写字母或下划线组成的字符串，包含在白名单中的配置项，不再做规则检查。 |
| 其他 | packageType | 包类型 | 可选 | 字符串 | InterfaceHar | 标识模块是否为 HSP 包，在新建 Shared Library 时会自动生成该字段，并默认赋值为 "InterfaceHar"；Static Library 中没有该字段，表示为普通 HAR 包。 |
| 其他 | dependencyMode | BundledHar 类型 | 可选 | 字符串 | loose | 该字段由编译构建自动生成，不推荐开发者手动配置。用于标识当前 HAR 包编译时是否开启 bundledAllDependencies。若开启填入 bundled，若未开启填入 loose 或缺省。三方中心仓仅支持 bundled 和 loose 两种取值，其他取值会导致校验失败。 |
注意：
依赖名使用要求：
- 在
oh-package.json5文件中dependencies、devDependencies、dynamicDependencies节点声明本地依赖时，允许配置的依赖名和依赖包的包名（即包内oh-package.json5中配置的 name）不一致，但不推荐该用法，在默认情况下 ohpm 会通过告警日志来提示此类问题。若希望将告警升级为报错并中断命令执行，可以通过在.ohpmrc中配置enforce_dependency_key=true；或在项目级build-profile.json5文件中将strictMode字段下配置useNormalizedOHMUrl=true。 - 使用参数化配置时，依赖名和依赖包的包名（即包内
oh-package.json5中配置的 name）必须保持一致，否则会报错并中断命令执行。 - 在
oh-package.json5、overrideDependencyMap、parameterFile文件中，不建议使用无效的转义字符（例如：\a、\e、\o等）或 Unicode 编码（例如：\uxxxx）。
兼容性字段配置示例
三方库开发者使用的 SDK 和当前集成该三方库工程编译时使用的 SDK 可能存在不一致的情况。因此，ohpm 新增了兼容性检测相关配置以帮助 SDK 做兼容性分析。配置示例如下：
{
"name": "library",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "Index.ets",
"license": "Apache-2.0",
"dependencies": {
"liblibrary.so": "file:./src/main/cpp/types/liblibrary"
},
"compatibleSdkVersion": "12",
"compatibleSdkType": "HarmonyOS",
"obfuscated": false,
"nativeComponents": [
{
"name": "liblibrary.so",
"compatibleSdkVersion": "12",
"compatibleSdkType": "HarmonyOS"
}
]
}
创建一个新的 oh-package.json5 文件
通过命令行创建 oh-package.json5 文件，执行如下命令：
导航到包的目录。
cd /path/to/package
执行初始化命令，并按照问卷填写相关参数。
对无命名空间模块，执行以下命令：
ohpm init
对有命名空间模块，执行以下命令：
ohpm init --group group_name
若跳过问卷填写，创建默认文件，可在初始化命令行加上配置参数 --yes。
ohpm init --yes
默认创建的 oh-package.json5 文件示例：
{
"name": "package_name",
"version": "1.0.0",
"description": "",
"main": "index.ts",
"author": "",
"license": "ISC",
"dependencies": {}
}
依赖配置说明
ohpm 存在 dependencies，devDependencies 和 dynamicDependencies 三种依赖类型。同时支持具体版本号，范围版本号，tag 标签，本地 har/tgz 文件路径、本地源码目录和使用 @module 通过模块名指向模块目录（示例："module_key": "@module:module_name"）多种方式引入依赖。当依赖的三方库版本号配置为 * 时，表示当前依赖的包版本为该三方库的最新包版本。
说明：
- 从 DevEco Studio 6.0.0 Beta1 开始支持
@module配置方式；从 DevEco Studio 6.0.2 Beta1 开始，通过devDependencies引入的依赖，不校验循环依赖。 @module配置中，module_name必须在project/build-profile.json5文件或者project/.hvigor/dependencyMap/dependencyMap.json5（hvigor 生成）文件的 modules 节点下存在。@module配置中，module_key需和"@module:module_name"指向的模块目录下oh-package.json5文件中配置的 name 一致。
dependencies：生产依赖，即参与编译/运行阶段使用的依赖，用来定义生产态 HAR/HSP 包依赖，声明在代码中被 import 的三方库。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（手机）上使用，则必须配置。devDependencies：开发态依赖，只能参与项目的开发或测试阶段的依赖。如果被依赖的组件最终要与依赖的组件一起发布到目标机器（如手机）上使用，则不能配置在该字段中。通过devDependencies引入的依赖，不校验循环依赖。dynamicDependencies：动态依赖，用来配合动态 import，表达动态 import 使用的 HSP 包依赖。动态依赖不会在加载时就被编译，而是根据条件导入模块或者按需导入模块，具有更高效的依赖加载速度。
依赖配置示例：
{
"dependencies": {
// 具体版本号引入，支持符合semver标准的版本号
"specific_version": "1.0.0",
// 范围版本号引入，^引入1.x.x的最新版本，~引入1.0.x的最新版本。范围版本优先选取正式版本，无匹配的正式版本才会选取先行版本
"scope_version": "^1.0.1",
// tag标签引入，示例引入标签为"beta"对应的版本号
"tag_version": "tag:beta",
// 本地文件引入，可引入本地har/tgz文件
"local_file": "file:./xx.har",
// 本地源码引入，可引入本地其他模块的源码，示例直接引入本地的"module1"模块
"local_source_code": "file:../module1"
// 项目存在Foo模块，即build-profile.json5文件或dependencyMap.json5文件中modules节点下存在名称为Foo的模块；该模块Foo的oh-package.json5中name为：foo_test
"foo_test": "@module:Foo"
},
"devDependencies": {
// 支持依赖引入类型同dependencies
},
"dynamicDependencies": {
// 支持依赖引入类型同 dependencies
}
}
devDependencies 引入的依赖，不校验循环配置示例：
如下 oh-package.json5 配置所示，模块 ma 通过配置 dependencies 依赖模块 mb，同时模块 mb 通过配置 devDependencies 依赖模块 ma，进而构造成循环依赖。
// 模块ma的oh-package.json5
{
"name": "ma",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "Index.ets",
"author": "",
"license": "Apache-2.0",
"dependencies": {
"mb": "../mb"
}
}
// 模块mb的oh-package.json5
{
"name": "mb",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "Index.ets",
"author": "",
"license": "Apache-2.0",
"devDependencies": {
"ma": "../ma"
}
}
overrides
ohpm 客户端在 1.4.0 版本开始支持 Override 机制，可以在项目级别的 oh-package.json5（即项目根目录下的 oh-package.json5）文件中添加 overrides 配置，方便将依赖树中的依赖替换为另一个版本。替换的版本可以是一个具体的版本号或模糊版本、本地存在的 HAR 包或源码目录、parameterFile 配置（示例："foo": "@param:dependencies.foo"），也可以使用 @module 通过模块名指向模块目录（示例："module_key": "@module:module_name"）。
例如，想要确保 foo 始终安装 1.0.0 版本，可以在项目级的 oh-package.json5 中增加如下配置：
说明：
overrides必须配置在项目级别的oh-package.json5中，配置在模块级别的oh-package.json5中将不会生效。- 从 DevEco Studio 6.0.0 Beta1 开始支持
@module配置方式。 @module配置中module_name必须在project/build-profile.json5文件或者project/.hvigor/dependencyMap/dependencyMap.json5（hvigor 生成）文件的 modules 节点下存在，否则报错处理。@module配置中，module_key需和"@module:module_name"指向的模块目录下oh-package.json5文件中配置的 name 一致，否则报错处理。
{
"overrides": {
"foo": "1.0.0"
}
}
若本地存在 foo 的源码、HAR 包或者 @module 配置，想确保 foo 始终使用您本地的版本，可以在项目级的 oh-package.json5 中如下配置：
{
"overrides": {
// 项目存在Foo模块，即build-profile.json5文件或dependencyMap.json5文件中modules节点下存在名称为Foo的模块；该模块Foo的oh-package.json5中name为：foo_test
// "foo_test": "@module:Foo"
// 本地存在"foo"的源码目录，如项目根目录下的foo目录
// "foo": "file:./foo"
// 本地存在"foo"的HAR文件，如项目根目录下的libs目录中的foo.har
"foo": "file:./libs/foo.har"
}
}
exclusions
ohpm 客户端在 5.3.0 版本开始支持 exclusions 机制，可以在项目级 oh-package.json5（即项目根目录下的 oh-package.json5）文件中添加 exclusions 配置，即可实现移除第三方依赖（远程依赖、本地文件依赖）中的一个或多个子依赖。
配置说明
配置格式：
// key: value形式配置
"[@group/]libname[@spec]" : ['exclude_sub_libname']
配置 key 部分：[@group/]libname[@spec]，代表需要做子依赖排除的依赖名称及其版本，'[]' 代表该内容为可选配置。当依赖没有组织名称时，[@group/] 部分可不配置；当不需要精确匹配具体版本号或具体某个本地文件依赖时，[@spec] 部分可不配置；spec 可以是一个具体的版本号、本地文件路径（支持相对路径和绝对路径，配置为相对路径时指相对于项目根路径）。
配置 value 部分，['exclude_sub_libname'] 是一个字符串数组，可配置多个，代表需要被排除的子依赖名称列表。
配置示例：
{
"exclusions": {
"@ohos/lib1@1.0.0": ['@ohos/sub_lib1'] // 排除远程依赖@ohos/lib1的子依赖：@ohos/sub_lib1
"@ohos/lib2@./lib2.har": ['@ohos/sub_lib2'] // 排除本地文件依赖@ohos/lib2的子依赖：@ohos/sub_lib2
}
}
配置约束：
exclusions必须配置在项目级别的oh-package.json5中，配置在模块级别的oh-package.json5中将不会生效。exclusions配置只能移除远程依赖、本地文件依赖的子依赖，对源码依赖不生效。exclusions只能移除dependencies、dynamicDependencies下配置的依赖。exclusions中配置的 key 不能和overrideDependencyMap中配置的 key 一致，否则报配置冲突错误并中断程序。- 自动解决依赖版本冲突功能开启（
.ohpmrc中resolve_conflict=true）后，如果exclusions配置中配置项指定了 spec，但 spec 对应的依赖在版本决策中被移除时，exclusions配置将不会生效；建议该场景下不要配置 spec 部分。
示例
下面演示如何移除远程依赖或本地文件依赖的 oh-package.json5 中 dependencies、dynamicDependencies 下配置的依赖。示例中以 <project> 代表项目根路径进行说明。
1、模块级 oh-package.json5 内容如下，将安装依赖 @ohos/lib1、@ohos/lib2。
{
"name": "entry",
"version": "1.0.0",
"description": "Please describe the basic information.",
"dependencies": {
"@ohos/lib1": "1.0.0" // 远程依赖
"@ohos/lib2": "file:../lib2.har" // 本地文件依赖
}
}
// @ohos/lib1的oh-package.json5配置
{
"name": "@ohos/lib1",
"version": "1.0.0",
"description": "Please describe the basic information.",
"dependencies": {
"@ohos/lib1_sub1": "1.0.0" // 子依赖1
"@ohos/lib1_sub2": "2.0.0" // 子依赖2
}
}
// @ohos/lib2的oh-package.json5配置
{
"name": "@ohos/lib2",
"version": "1.0.0",
"description": "Please describe the basic information.",
"dependencies": {
"@ohos/lib2_sub1": "1.0.0" // 子依赖1
"@ohos/lib2_sub2": "2.0.0" // 子依赖2
}
}
2、项目级 oh-package.json5 内容如下，添加 exclusions 配置，其中 lib2.har 放置在项目根目录下。
{
"modelVersion": "6.1.1",
"description": "Please describe the basic information.",
"exclusions": {
"@ohos/lib1@1.0.0": ['@ohos/lib1_sub1'], // 排除远程依赖@ohos/lib1的子依赖：@ohos/lib1_sub1
"@ohos/lib2@./lib2.har": ['@ohos/lib2_sub2'] // 排除本地文件依赖@ohos/lib2的子依赖：@ohos/lib2_sub2
}
}
3、执行 ohpm 安装命令。
ohpm install --all
4、ohpm 安装完成后，在 entry 目录下执行：ohpm list -d 10，打印依赖结构如下。
entry 1.0.0 <project>\entry
├─┬ @ohos/lib1 1.0.0
│ └── @ohos/lib1_sub2 1.0.0 // 安装了子依赖@ohos/lib1_sub2,@ohos/lib1_sub1已被排除
├─┬ @ohos/lib2 <project>\lib2.har
└── @ohos/lib2_sub1 1.0.0 // 安装了子依赖@ohos/lib2_sub1,@ohos/lib2_sub2已被排除
作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。
更多推荐
52
0- 0
已为社区贡献27条内容
所有评论(0)