👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 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。

涉及的主要工程能力是:

内容本文使用情况
HarmonyOSHarmonyOS 7 背景
API LevelAPI 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 解析失败或者打包内容不符合预期,可以按下面的顺序检查:

  1. 看依赖属于什么阶段。
    正式代码需要,却放在 devDependencies,优先修正分类。

  2. 确认是不是动态 HSP。
    不要因为出现动态 import 就直接使用 dynamicDependencies。

  3. 核对依赖名。
    oh-package.json5 中的 key、依赖模块自己的 name、源码 import 名称尽量保持一致。

  4. 检查模块路径。
    file:../common 这样的本地依赖要确认真实目录存在。

  5. 执行 Sync Now。

  6. 检查实际安装依赖。
    可以使用 ohpm list 查看当前已经安装的三方库及依赖关系。官方当前的 ohpm list 支持树形查看直接依赖和更深层级的依赖。

  7. 最后再检查动态 import 的构建选项。
    如果使用变量形式动态 import,再确认 runtimeOnly 等配置是否满足当前官方要求。

这个顺序的好处是先排除“依赖关系写错”这种基础问题,再进入 ArkTS 动态加载和 Hvigor 构建配置,不容易一开始就在复杂构建日志里绕圈。

开发经验总结

把三种依赖压缩成一句话,可以这样记:

dependencies
= 正式代码编译、运行需要的生产依赖

devDependencies
= 开发、测试阶段使用的依赖

dynamicDependencies
= 需要动态加载的 HSP 依赖

但真正开发时还应该再补一句:

动态 import 不等于 dynamicDependencies,HSP 也不代表永远只能写进 dynamicDependencies。

HAR、HSP、普通 OHPM 包属于“模块和包的形态”,dependencies 等字段描述的是“依赖关系”;而普通 import、动态 import 又属于“代码加载方式”。

把这三个维度拆开以后,很多看起来复杂的依赖问题其实会清楚不少:

模块是什么?
    +
为什么依赖它?
    +
什么时候加载它?

分别回答这三个问题,再去写 oh-package.json5,比根据字段名字猜配置可靠得多。

如果正在整理一个模块比较多的 HarmonyOS 工程,可以顺手检查一下现有 devDependencies:里面是否存在业务源码真正会调用的库? 这一类配置最值得优先排查。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐