ohpm 速查手册 — OpenHarmony 包管理器
# 📦 ohpm 速查手册（OpenHarmony Package Manager）
ohpm 是鸿蒙生态的包管理器（≈ npm），管理工程的三方库依赖。注意与 hdc 的分工：ohpm 在本机工程侧拉依赖（
oh-package.json5→oh_modules），hdc 在设备侧调试安装——两者互不包含、都需要。 全部命令在 ohpm 6.0.1（DevEco Studio 5.x 自带）上实测验证。
# 🗺️ 19 个命令总览
| 命令（别名） | 一句话 |
|---|---|
install (i) | 安装依赖（包/版本/tag/本地目录/har 文件） |
uninstall (un) | 卸载包 |
update (up) | 按语义范围更新 |
list (ls) | 依赖图（-d 控深度、-r 全模块） |
info | 包详情（可查单个字段） |
init | 生成 oh-package.json5 |
version | 版本号递增（major/minor/patch） |
run | 运行 scripts |
clean (cls) | 删工程全部 oh_modules + 锁文件 |
root | 打印生效的 oh_modules 路径 |
ping | 测 registry 连通性 |
config | 配置管理（set/get/delete/list/encrypt） |
cache | 缓存管理（cache clean） |
publish | 发布 har/tgz 到 registry |
prepublish | 发布前校验包内容 |
unpublish | 撤回发布（-f 全版本） |
dist-tags | 管理版本 tag |
convert | npm 包转 ohpm 包 |
help | 帮助 |
# 0. 环境与版本
ohpm -v # 实测 6.0.1；随 DevEco Studio 发布（tools/ohpm/bin），不要用 npm 安装
1
⚠️ node 版本踩坑（实测）：ohpm 启动脚本直接调 PATH 里的
node。PATH 里是老版本 node（如 v14）时会报Cannot find module 'node:events'。把 DevEco 自带 node（v18）放 PATH 最前，或设NODE_HOME：
export PATH=/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH
1
# 1. 安装与卸载（install / uninstall / update）
ohpm install # 安装 oh-package.json5 全部依赖
ohpm install pkg # 安装并写入 dependencies（实测写入 "^2.1.0" 语义范围）
ohpm install [email protected] # 指定版本
ohpm install pkg@tag:latest # 按 tag
ohpm install ./libs/mylib # 本地目录
ohpm install mylib.har # har 文件
ohpm install --all # 安装工程内所有模块的依赖（多模块工程必用）
ohpm install --save-dev pkg # 写入 devDependencies
ohpm install --save-dynamic pkg # 写入 dynamicDependencies
ohpm install --no-save pkg # 只装不写配置
ohpm install --no-link pkg # 实体拷贝而非符号链接（默认是链接）
ohpm install --resolve_conflict_strict # 依赖冲突时严格报错（默认宽松处理）
ohpm uninstall pkg
ohpm uninstall --no-save pkg # 只删不写配置
ohpm update # 按语义范围更新
ohpm update --all-modules # 更新所有模块
ohpm update --tag-filter '^\d+\.\d+' # 只更新按 tag 指定且匹配正则的依赖
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 2. 查询（list / info / root / ping）
ohpm list # 当前模块依赖图
ohpm list -d 0 # 深度 0（只看直接依赖）
ohpm list -r # 全模块递归
ohpm list --json # JSON 输出
ohpm info pkg # 包详情（版本/描述/仓库）
ohpm info pkg versions # 查单个字段
ohpm root # 打印生效的 oh_modules 目录
ohpm ping # 测 registry 连通性
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 3. 工程文件：oh-package.json5
真实结构（多模块工程实测）：
{
"modelVersion": "5.0.3",
"name": "my-app",
"version": "1.0.0",
"main": "",
"dependencies": { // 运行时依赖
"@ohos/lottie": "2.0.16",
"pako": "2.1.0"
},
"devDependencies": { // 开发依赖
"@ohos/hypium": "1.0.16", // 官方单测框架
"@ohos/hamock": "1.0.0" // 官方 mock 框架
},
"dynamicDependencies": {}, // 动态依赖
"overrides": { // ★ 强制统一传递依赖版本（依赖冲突的解法）
"@ohos/protobufjs": "2.1.0"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
要点：
- json5 格式：允许注释、单引号、尾逗号
file:协议：本地模块直接引用，如"mylib": "file:./../mylib"（多仓库联调常用）- 作用域包：
@ohos/xxx（官方）、@group/xxx（组织） - 锁文件
oh-package-lock.json5：提交入库，CI 按锁安装保证版本一致 oh_modules/：依赖落盘目录（默认符号链接结构，类似 pnpm）
# 4. Registry 配置（config）
ohpm config set registry https://ohpm.openharmony.cn/ohpm/ # 官方源（ohpm 源码默认值）
ohpm config get registry
ohpm config list # 查看全部配置
ohpm config delete <key> # 删除配置项
# 单次覆盖（不动全局配置）
ohpm install --registry https://your-private-ohpm-registry/
ohpm install --strict_ssl false # 跳过证书校验（内网源自签证书时）
ohpm install --fetch_timeout 60000 # 网络超时（毫秒）——注意是命令参数，不是 config 键
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
❌ 实测无
timeout/proxy配置键（config get返回 undefined）。超时用--ft/--fetch_timeout参数；代理需在 shell 层面解决。
# 5. 缓存与清理（cache / clean）
ohpm cache clean # 清全局缓存目录
ohpm clean # 删工程全部 oh_modules + 锁文件
ohpm clean --kl # 保留锁文件只删 oh_modules
1
2
3
2
3
# 6. 脚本与版本（run / version / init）
ohpm init # 交互式生成 oh-package.json5
ohpm init -y # 全默认
ohpm init -g mycompany # 指定 group
ohpm run build # 运行 oh-package.json5 的 scripts
# scripts 示例："scripts": { "build": "hvigorw assembleHap" }
ohpm version patch # 1.0.0 → 1.0.1
ohpm version minor # 1.0.0 → 1.1.0
ohpm version major # 1.0.0 → 2.0.0
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# 7. 发布（publish / prepublish / dist-tags / unpublish / convert）
发布物是 .har（HarmonyOS Archive）或 .tgz。认证方式是 publish_id + SSH 私钥（registry 侧申请 publish_id，本地配私钥路径）——没有 login 命令。
ohpm prepublish mylib.har # 发布前校验
ohpm publish mylib.har # 发布
ohpm publish mylib.har -t beta # 发布并打 tag
ohpm publish --publish_registry https://your-registry/ --publish_id <id> --key_path ~/.ssh/id_rsa
ohpm dist-tags ls mylib # 查看全部 tag
ohpm dist-tags add [email protected] beta # 给版本打 tag
ohpm dist-tags update [email protected] beta # 把 tag 移到新版本
ohpm dist-tags rm mylib beta # 删除 tag
ohpm unpublish [email protected] # 撤回指定版本
ohpm unpublish mylib -f # 撤回全部版本（危险）
ohpm convert some-npm-pkg # npm 包转 ohpm 包
ohpm convert ./node_modules --publish # 整目录转换并发布
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 8. npm ↔ ohpm 对照表
| npm | ohpm | 备注 |
|---|---|---|
package.json | oh-package.json5 | json5，支持注释 |
package-lock.json | oh-package-lock.json5 | 提交入库 |
node_modules | oh_modules | 默认符号链接（≈ pnpm） |
npm install -S | ohpm install（默认写 dependencies） | |
npm install -D | ohpm install --save-dev | ✅ 存在 |
npm install -g | ❌ 不存在 | 无全局安装概念 |
npm ls | ohpm list（-d 控深度） | ✅ 存在 |
npm view | ohpm info | |
npm cache clean | ohpm cache clean | ✅ 存在 |
npm run | ohpm run | |
npm init | ohpm init | |
npm version | ohpm version | |
npm publish | ohpm publish | 认证是 publish_id + SSH key，非 login |
npm dist-tag | ohpm dist-tags | |
npm config | ohpm config | set/get/delete/list |
npm search / audit / outdated / shrinkwrap / login | ❌ 均不存在 | 网页端搜索：ohpm.openharmony.cn |
# 9. 常见问题（实测踩坑）
| 症状 | 原因与解法 |
|---|---|
Cannot find module 'node:events' | PATH 里 node 版本过老（如 v14）。DevEco 自带 node v18 放 PATH 最前（§0） |
| 网络超时 | ohpm ping 测连通 → 换源 config set registry → --fetch_timeout 调超时 |
| 依赖冲突/版本不一致 | ohpm list -d 0 定位 → overrides 字段强制统一版本（§3） |
| 锁文件损坏 | rm oh-package-lock.json5 && ohpm install 重新生成 |
| oh_modules 状态异常 | ohpm clean --kl（保锁）→ ohpm install；再不行 ohpm cache clean |
| 内网源自签证书报错 | --strict_ssl false |
| 多模块工程依赖没装全 | 忘了 --all：ohpm install --all |
# 10. 与其他工具的关系
| 工具 | 类比 | 职责 |
|---|---|---|
| ohpm | npm | 本机工程：拉三方库依赖进 oh_modules |
| hvigor | gradle | 本机工程：构建（构建时调用 ohpm 产物） |
| hdc | adb | 设备：安装/日志/转储，见 hdc |
上次更新: 2026/10/09, 15:51:11