HarmonyOS 多模块项目中的公共库治理与最佳实践

2026年1月13日 20:43

在 鸿蒙（HarmonyOS）多模块项目 中，如果你希望 避免在每个模块（Module）中重复集成同一个三方库或公共库，可以将该库 提升到项目级别（Project-level）进行统一管理。以下是标准做法，适用于 Stage 模型 + ArkTS + DevEco Studio 的工程结构。

✅ 目标

将公共库（如 @ohos/utils、自研工具库、第三方 npm 包等）只声明一次，供多个模块（entry、feature、service 等）共享使用。

📁 鸿蒙项目结构回顾

MyHarmonyProject/
├── build-profile.json5        ← 项目级构建配置
├── oh-package.json5           ← 项目级依赖（关键！）
├── modules/
│   ├── entry/                 ← 主模块
│   ├── feature_news/          ← 功能模块1
│   └── feature_ebook/         ← 功能模块2
└── libs/                      ← （可选）本地 aar/har 公共库

✅ 正确做法：在项目根目录的 `oh-package.json5` 中声明依赖

步骤 1：在项目根目录的 `oh-package.json5` 中添加依赖

{
  "devDependencies": {
    // 开发依赖（如 types）
  },
  "dependencies": {
    // 👇 把公共库放在这里（项目级）
    "@ohos/utils": "1.0.0",
    "some-third-party-lib": "^2.3.0"
  }
}

✅ 这样，所有子模块都可以继承使用这些依赖，无需在每个 module/xxx/oh-package.json5 中重复声明。

步骤 2：删除各子模块中的重复依赖

确保 modules/entry/oh-package.json5、modules/feature_news/oh-package.json5 等 不再包含 已提升到项目级的依赖。

例如，不要在 entry/oh-package.json5 中再写：

{
  "dependencies": {
    "@ohos/utils": "1.0.0"  // ❌ 删除这行！
  }
}

步骤 3：在子模块代码中正常 import 使用

// 在 entry 或 feature_news 模块中
import { ZGJYBAppearanceColorUtil } from '@ohos/utils';

// ✅ 可以正常使用，因为依赖已由项目级提供

⚠️ 注意事项

1. 仅适用于 `npm` 类型的包（通过 `ohpm` 安装）

如果你是通过 ohpm install @ohos/utils 安装的库，它会被记录在 oh-package.json5。
这种方式支持 依赖提升（hoisting） ，类似 npm/yarn 的 workspace。

2. 本地 `.har` 或 `.hap` 库不能这样共享

如果你的“库”是一个 本地开发的 .har（HarmonyOS Archive）模块，则需要：
- 将其放在 libs/ 目录下；
- 在 每个需要使用的模块 的 module.json5 中声明 deps 引用；
- 或者将其发布为私有 ohpm 包，再通过 oh-package.json5 引入。

示例：引用本地 har（仍需逐模块配置）

// modules/entry/module.json5
{
  "deps": [
    "../libs/my-common-utils.har"
  ]
}

❌ 这种情况无法完全避免重复声明，但你可以通过脚本或模板减少工作量。

3. 确保 DevEco Studio 同步了依赖

修改 oh-package.json5 后，点击 “Sync Now” 或运行：
```
ohpm install
```
在项目根目录执行，会安装所有模块共享的依赖。

✅ 最佳实践总结

场景	推荐方案
公共 npm/ohpm 库（如 `@ohos/utils`）	✅ 在项目根目录 `oh-package.json5` 中声明一次
自研公共逻辑（TS 工具函数）	✅ 创建一个 `shared` 模块，发布为 `ohpm` 私有包，再在项目级引入
本地 `.har` 库	⚠️ 需在每个模块的 `module.json5` 中引用，但可统一放在 `libs/` 目录管理
避免重复代码	✅ 抽象公共组件/工具到独立模块，通过依赖注入使用

🔧 附加建议：创建 `shared` 模块（高级）

新建模块：File > New > Module > Static Library (HAR)
- 命名为 shared
在其中放置公共工具类、常量、网络封装等

在 shared/oh-package.json5 中定义包名：

{ "name": "@myorg/shared", "version": "1.0.0" }

在项目根目录运行：
```
ohpm install ./modules/shared --save
```

然后在 oh-package.json5 中就会出现：

"dependencies": {
  "@myorg/shared": "file:./modules/shared"
}

所有模块即可通过 import { xxx } from '@myorg/shared' 使用。

✅ 这是最接近“项目级公共库”的鸿蒙官方推荐方案。

✅ 结论

把公共库写在项目根目录的 oh-package.json5 的 dependencies 中，即可实现“一次集成，多模块共享” 。

只要你的库是通过 ohpm 管理的（包括本地 file: 引用），就支持这种共享机制。这是 HarmonyOS 多模块项目的标准依赖管理方式。

阅读视图