HarmonyOS 依赖配置实践:dependencies、devDependencies、dynamicDependencies 到底怎么分【鸿蒙心迹】-3

👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀
前言
在 HarmonyOS 工程里,oh-package.json5 中最容易被混用的三个字段,可能就是 dependencies、devDependencies 和 dynamicDependencies。
它们看起来都在“声明依赖”,但实际承担的职责并不一样:生产代码要使用的库属于生产依赖,开发或测试工具属于开发依赖,而 dynamicDependencies 又不是另一个“可选依赖区”,它有明确的使用对象——需要动态加载的 HSP 模块。华为当前官方文档已经明确区分了这三种依赖类型。
这篇文章不讨论复杂业务,而是搭一个尽量小的三模块工程,把三种依赖放到真实的工程关系中看清楚:
DependencyDemo
├── entry # HAP,应用入口
├── common # HAR,公共代码
└── featureHsp # HSP,动态共享能力
同时在 entry 中保留一个测试框架作为 devDependencies 示例。这样基本覆盖了日常 HarmonyOS 模块化工程里最常见的几种依赖关系。
一、三种依赖为什么特别容易写错
问题不在 JSON5 语法,而在“依赖”这个词本身太宽泛。
很多开发者会自然形成这样的判断:
代码里 import 了
↓
那就写到 dependencies
这个规则对普通运行时依赖大体成立,但无法解释 HSP 动态加载,也无法区分只参与开发和测试的工具。
反过来,如果从 npm 的使用习惯出发,又可能认为:
dependencies -> 发布环境
devDependencies -> 本地开发环境
dynamicDependencies -> 动态 import
第三条尤其容易出错。
HarmonyOS 官方对当前三个字段的定义是:
dependencies:生产依赖,代码需要使用,参与编译和运行阶段。devDependencies:用于开发或测试阶段。dynamicDependencies:配置需要动态加载的 HSP 模块。
所以有一个非常重要的结论:
dynamicDependencies不等于“所有使用import()的模块”。
HarmonyOS 的动态 import() 本身可以用于 HSP、HAR、OHPM 包、Native 库等场景;官方关于第三方字节码 HAR 的说明也明确提到,动态 import 可以加载多种模块。换句话说,“动态 import 语法”和“dynamicDependencies 字段”不是同一个概念。
真正判断依赖应该放在哪里时,要先问:
它在工程中扮演什么角色?
二、先确认版本和能力边界
华为 2026 年 8 月开发者月刊明确指出,HarmonyOS 7 对应 API 26。本文以当前 HarmonyOS 7 / API 26 开发环境为背景,但讨论的核心是 OHPM 与 Hvigor 的工程依赖配置,而不是某个新增于 API 26 的系统接口。
因此这里没有需要申请的系统权限,也没有某个业务 Kit 需要 import。
涉及的主要工程能力是:
| 内容 | 本文使用情况 |
|---|---|
| HarmonyOS | HarmonyOS 7 背景 |
| API Level | API 26 |
| 包管理 | OHPM |
| 构建系统 | Hvigor |
| 配置文件 | oh-package.json5、build-profile.json5 |
| 模块类型 | HAP、HAR、HSP |
| 系统权限 | 本示例无额外权限 |
| Stage 模型 | 示例按照当前 Stage 工程组织 |
官方对应用程序包术语的定义也很清晰:HAR 是静态共享包,用于编译态复用;HSP 是动态共享包,用于运行时复用。多个模块引用 HAR 时可能产生代码、资源的重复拷贝,而 HSP 可以保持单份共享代码和资源。
这也是理解三种依赖之前需要建立的基础。
三、dependencies:真正的生产代码依赖
先看最常见的一种。
假设 common 是一个 Static Library,也就是 HAR 模块,里面提供字符串处理、日期转换或者通用业务模型。
例如我们在 common/Index.ets 对外暴露一个非常简单的方法:
export function getCommonMessage(): string {
return 'message from common HAR';
}
entry 的页面需要直接调用它,那么 entry/oh-package.json5 应把 common 放进 dependencies:
{
"name": "entry",
"version": "1.0.0",
"description": "Dependency demo entry module",
"main": "",
"author": "",
"license": "",
"dependencies": {
"common": "file:../common"
}
}
业务代码再按照模块暴露的接口使用:
import { getCommonMessage } from 'common';
const message: string = getCommonMessage();
这里的判断并不复杂:
应用正式代码需要它,并且编译、运行过程都依赖它,因此属于 dependencies。
官方构建 FAQ 还有一个很有价值的反例:如果某个包把实际上运行时需要的依赖错误地放在 devDependencies 中,源码继续引用该依赖的 API,可能出现 OhmUrl 无法解析等编译问题。官方给出的处理方向同样是——运行时依赖不能错误配置成 devDependencies。
所以不要根据“这个库是团队内部开发的”“它只是工具代码”来判断。
关键问题始终是:
发布后的代码运行时还需不需要它?
需要,就不能只放在 devDependencies。
四、devDependencies:不是“次要依赖”
devDependencies 最容易出现的误解,是把它理解成:
不太重要的依赖。
实际上完全不是这个意思。
它表示开发阶段或测试阶段需要的依赖。官方当前说明也是如此。
例如测试框架、测试辅助工具属于典型场景。
华为当前 ohpm list 官方文档的示例依赖树中仍展示了 @ohos/hypium 1.0.6。如果工程使用对应版本进行测试,可以看到类似这样的配置关系;具体版本应以当前 DevEco Studio 创建的测试工程及实际安装结果为准,而不是机械复制示例版本。
示意配置如下:
{
"devDependencies": {
"@ohos/hypium": "1.0.6"
}
}
这里最重要的不是 Hypium 本身,而是分类原则:
正式业务代码运行需要
↓
dependencies
仅开发、测试阶段需要
↓
devDependencies
官方还明确给出了 HAR 构建层面的差异:在特定构建场景中,HAR 构建只会把符合条件、位于 dependencies 中的本地依赖一起处理,devDependencies 中的依赖不会按生产依赖方式打入 HAR。
因此,把正式代码依赖错误放进 devDependencies,并不是单纯“分类不漂亮”。
它可能直接改变构建结果。
五、dynamicDependencies:重点是 HSP,不是“动态”两个字
第三种才是最容易混淆的。
官方目前对 dynamicDependencies 的描述非常明确:
用于配置动态加载的 HSP 模块。
我们把第三个模块 featureHsp 创建为 Shared Library,也就是 HSP。
HSP 本身属于动态共享包。官方定义中,它能够包含代码、C++ 库、资源和配置文件,并支持运行时复用;应用内 HSP 与宿主应用具有较强的应用级关联。
如果 entry 要把 featureHsp 作为动态 HSP 依赖管理,可以这样组织:
{
"dynamicDependencies": {
"featureHsp": "file:../featureHsp"
}
}
这时三个字段放到一起,就比较直观了:
{
"name": "entry",
"version": "1.0.0",
"description": "Dependency demo entry module",
"main": "",
"author": "",
"license": "",
"dependencies": {
"common": "file:../common"
},
"devDependencies": {
"@ohos/hypium": "1.0.6"
},
"dynamicDependencies": {
"featureHsp": "file:../featureHsp"
}
}
对应关系变成:
common
↓
正式运行代码直接依赖
↓
dependencies
@ohos/hypium
↓
测试阶段使用
↓
devDependencies
featureHsp
↓
需要动态加载的 HSP
↓
dynamicDependencies
这个分类比“静态、开发、动态”几个字面标签更可靠。
六、动态 import 和 dynamicDependencies 不要混为一谈
这里值得单独拆出来。
ArkTS 支持动态 import。官方资料中给出的 HSP 动态导入代码可以出现类似这样的形式:
import('hsplibrary/src/main/ets/utils/Logger').then(logger => {
logger.default.warn('this is logger warn');
});
官方构建资料同时指出,动态 import 不只用于 HSP,也可以涉及 HAR、OHPM 包和 Native 库。
因此下面这个推理是错误的:
看到 import(...)
↓
一定放 dynamicDependencies
例如某个 HAR 通过变量动态 import,并不意味着它自动变成 HSP,也不意味着就应该改进 dynamicDependencies。
对于变量形式的动态 import,构建系统还可能涉及模块级 build-profile.json5 中 arkOptions.runtimeOnly 的配置。官方第三方字节码 HAR 排查文档明确给出了这种情况:如果变量动态 import 的模块没有被正确加入 runtimeOnly.packages,运行时可能找不到对应模块。
所以最好把两个问题彻底分开:
问题一:模块是什么依赖类型?
决定 dependencies / devDependencies / dynamicDependencies。
问题二:代码采用什么加载方式?
决定普通 import、动态 import,以及是否还需要额外构建配置。
这两个维度不能互相代替。
七、三模块示例怎么理解构建结果
回到前面的最小工程:
entry HAP
common HAR
featureHsp HSP
HAR 和 HSP 本身的构建语义不同。
官方应用程序包术语文档把 HAR 定义为静态共享包:代码和资源会跟随使用方参与编译,实现编译态复用。
HSP 则是动态共享包:可以独立编译,在运行期由多个模块复用。
这意味着 common 和 featureHsp 即使都在给 entry 提供公共能力,也不能简单理解成:
两个 library,只是文件后缀不同
它们解决的是不同问题。
HAR 更接近:
复用源码/字节码和资源
↓
跟随使用模块参与构建
HSP 更接近:
形成独立共享包
↓
运行时共享
官方对 HSP 还规定了明确约束,例如 HSP 需要和依赖它的 HAP 一同安装和运行,不能独立运行;HSP 可以依赖其他 HAR 或 HSP,但不支持循环依赖,也不支持依赖传递。
这也是为什么不能把 HSP 当成“更高级的 HAR”。
它是另一种包形态。
八、几个最常见的错误配置
1. 运行时代码依赖写进 devDependencies
例如:
{
"devDependencies": {
"common": "file:../common"
}
}
但业务代码却直接:
import { getCommonMessage } from 'common';
这种配置和字段语义冲突。
官方构建 FAQ 已经记录了类似问题:三方包将正式源码使用的依赖配置到 devDependencies,可能造成模块解析失败。
正确方向是把运行时真正需要的依赖调整到 dependencies。
2. 看到动态 import 就写 dynamicDependencies
例如一个 HAR:
const moduleName: string = 'common';
const commonModule = await import(moduleName);
这里应该先解决“动态 import HAR 的构建配置”问题,而不是因为出现 import() 就把 HAR 改成动态 HSP 依赖。
官方明确说明,动态 import 可以作用于 HAR、HSP 等不同模块。
3. 依赖名和实际模块名不一致
比如:
{
"dependencies": {
"Common": "file:../common"
}
}
模块自己的 oh-package.json5:
{
"name": "common"
}
这种名字不一致可能直接触发依赖校验问题。
当前官方 OHPM FAQ 明确指出,在启用标准化 OHMUrl 或相应依赖名校验的情况下,依赖使用的名字需要和依赖包自身 oh-package.json5 中的 name 保持一致。
实际工程建议直接统一:
"common": "file:../common"
代码也统一:
import { getCommonMessage } from 'common';
4. 修改配置后忘记同步工程
修改模块依赖后,需要让 DevEco Studio 重新同步工程。
华为官方工程使用指导明确提醒:修改 oh-package.json5 后需要执行 Sync Now,否则依赖修改不会正常生效。
5. 以为 ohpm install 成功就代表配置一定正确
ohpm install 的作用是安装依赖包,依赖包会进入相应模块的 oh_modules。
但是“安装成功”和“代码中的模块引用关系正确”是两回事。
例如:
main/types配置错误;- 依赖名大小写不一致;
- 运行时依赖写进
devDependencies; - 动态 import 缺少对应构建配置;
都可能在后续编译或运行阶段继续报错。官方构建 FAQ 对这些情况都有专门说明。
九、oh-package.json5 怎么整理更不容易出错
实际项目里,我更建议按照“生命周期”而不是“库的来源”分类。
可以采用下面这套判断顺序:
这个依赖是不是测试/开发工具?
│
├─ 是 → devDependencies
│
└─ 否
↓
它是不是需要按动态 HSP 依赖方式管理的 HSP?
│
├─ 是 → dynamicDependencies
│
└─ 否 → dependencies
不要使用这些判断方式:
三方库 → dependencies
自己写的库 → devDependencies
import() → dynamicDependencies
HAR → devDependencies
HSP → 一律 dynamicDependencies
这些规则都过于粗糙。
尤其是最后一条。HSP 有应用内 HSP、集成态 HSP 等不同集成方式。例如官方集成态 HSP 指导中,使用方是把集成态 HSP 的 tgz 包配置到 dependencies 中,而不是 dynamicDependencies。
这再次说明:
不能只看模块“是不是 HSP”,还要看具体使用方式和对应官方构建指导。
这也是配置依赖时最值得保留的习惯:先确定使用场景,再选择字段。
十、出现依赖问题时,建议按这个顺序排查
如果工程突然出现 Cannot find module、OhmUrl 解析失败或者打包内容不符合预期,可以按下面的顺序检查:
-
看依赖属于什么阶段。
正式代码需要,却放在devDependencies,优先修正分类。 -
确认是不是动态 HSP。
不要因为出现动态 import 就直接使用dynamicDependencies。 -
核对依赖名。
oh-package.json5中的 key、依赖模块自己的name、源码 import 名称尽量保持一致。 -
检查模块路径。
file:../common这样的本地依赖要确认真实目录存在。 -
执行 Sync Now。
-
检查实际安装依赖。
可以使用ohpm list查看当前已经安装的三方库及依赖关系。官方当前的ohpm list支持树形查看直接依赖和更深层级的依赖。 -
最后再检查动态 import 的构建选项。
如果使用变量形式动态 import,再确认runtimeOnly等配置是否满足当前官方要求。
这个顺序的好处是先排除“依赖关系写错”这种基础问题,再进入 ArkTS 动态加载和 Hvigor 构建配置,不容易一开始就在复杂构建日志里绕圈。
开发经验总结
把三种依赖压缩成一句话,可以这样记:
dependencies
= 正式代码编译、运行需要的生产依赖
devDependencies
= 开发、测试阶段使用的依赖
dynamicDependencies
= 需要动态加载的 HSP 依赖
但真正开发时还应该再补一句:
动态 import 不等于 dynamicDependencies,HSP 也不代表永远只能写进 dynamicDependencies。
HAR、HSP、普通 OHPM 包属于“模块和包的形态”,dependencies 等字段描述的是“依赖关系”;而普通 import、动态 import 又属于“代码加载方式”。
把这三个维度拆开以后,很多看起来复杂的依赖问题其实会清楚不少:
模块是什么?
+
为什么依赖它?
+
什么时候加载它?
分别回答这三个问题,再去写 oh-package.json5,比根据字段名字猜配置可靠得多。
如果正在整理一个模块比较多的 HarmonyOS 工程,可以顺手检查一下现有 devDependencies:里面是否存在业务源码真正会调用的库? 这一类配置最值得优先排查。
📝 写在最后
如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!
我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!
感谢你的阅读,我们下篇文章再见~👋
✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。
更多推荐

所有评论(0)