页面预览

前言

HarmonyOS 的依赖管理系统经历了从 @ohos 原生模块到 @kit Kit 化模块的重大演进。oh-package.json5 作为项目的依赖声明文件，管理着从测试框架到业务库的所有三方依赖。理解 @ohos 与 @kit 的模块化设计理念、依赖版本管理策略和多模块工程的依赖配置，是构建维护性良好的 HarmonyOS 应用的基石。本文以小事记（xiaoshiji_ohos_app） 的 oh-package.json5 和 oh-package-lock.json5 为切入点，深入解析 HarmonyOS 的依赖管理机制。

本文参考 HarmonyOS 官方文档：application-package-dev.md 和 application-package-fundamentals.md。

一、oh-package.json5 的作用

1.1 配置文件的作用域

HarmonyOS 工程中可能存在多个 oh-package.json5 文件，各自负责不同范围的依赖管理：

作用域 配置文件位置 管理范围 生效范围
工程级 工程根目录 所有模块共享的依赖 全局
模块级 各模块入口目录 该模块的依赖 模块内

小事记的依赖配置分别位于：

// 工程级 — 根目录 oh-package.json5
{
  "modelVersion": "6.0.2",
  "description": "Please describe the basic information.",
  "dependencies": {
  },
  "devDependencies": {
    "@ohos/hypium": "1.0.25",
    "@ohos/hamock": "1.0.0"
  }
}

// 模块级 — entry/oh-package.json5
{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}

1.2 关键字段说明

字段 说明 小事记中的值
name 模块名称，在发布时使用 entry
version 模块版本，遵循语义化版本 1.0.0
description 模块描述 "Please describe the basic information."
main 入口文件路径 ""（未使用）
dependencies 运行时依赖 {}
devDependencies 开发时依赖 @ohos/hypium, @ohos/hamock

二、@ohos 与 @kit 的模块化演进

2.1 演进背景

从 API 12 开始，HarmonyOS 引入了 Kit 化模块（@kit/xxx）来替代分散的 @ohos/xxx 原生模块。这一变化的核心目的是：

  1. 按场景聚合 — 将相关功能的模块聚合到同一个 Kit 中，减少导入路径的记忆成本
  2. 版本对齐 — 同一 Kit 内的模块版本号一致，避免版本兼容性问题
  3. 按需引入 — 开发者只需引入需要的 Kit，系统自动按需加载模块

2.2 @ohos 时代 vs @kit 时代

对比维度 @ohos 时代 @kit 时代
导入示例 import { UIAbility } from '@ohos.ability.abilityLifecycle' import { UIAbility } from '@kit.AbilityKit'
模块粒度 细粒度，每个功能一个模块 粗粒度，按场景聚合
版本管理 各模块独立版本号 Kit 内版本号统一
导入路径 分散，需要记忆多个路径 集中，一个 Kit 覆盖多个功能

2.3 小事记中的 Kit 化导入

小事记项目使用了 Kit 化导入方式：

// 使用 @kit 导入（推荐方式）
import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';

Kit 与对应功能的映射关系：

Kit 名称 包含的功能 替代的 @ohos 模块
@kit.AbilityKit UIAbility、Want、Configuration、AbilityConstant @ohos.ability.abilityLifecycle、@ohos.ability.want
@kit.ArkUI window、UIContext、动画、弹框 @ohos.arkui.window、@ohos.arkui.animation
@kit.CoreFileKit 文件操作、备份扩展 @ohos.file.fs、@ohos.file.backup
@kit.PerformanceAnalysisKit hilog、hiTrace、性能监控 @ohos.hilog、@ohos.hiTrace
@kit.DataKit preferences、relationalStore @ohos.data.preferences、@ohos.data.relationalStore

提示：在 API 12 及以上版本，推荐使用 @kit/xxx 方式导入。如果项目中仍在 import @ohos/xxx，建议迁移到 Kit 化导入方式。

三、依赖类型详解

3.1 dependencies 与 devDependencies

依赖类型 安装时机 是否包含在构建产物中 用途
dependencies 编译 + 运行时 ✅ 业务逻辑依赖
devDependencies 仅编译时 ❌ 测试框架、构建工具 
{
  "dependencies": {
    "@ohos/axios": "1.0.0",         // 网络请求库
    "@ohos/router": "2.0.0"         // 路由库
  },
  "devDependencies": {
    "@ohos/hypium": "1.0.25",       // 单元测试框架
    "@ohos/hamock": "1.0.0",        // Mock 测试框架
    "@ohos/hvigor": "5.0.0"         // 构建工具
  }
}

3.2 依赖的版本号格式

格式 含义 示例
1.0.0 精确版本 只安装 1.0.0
^1.0.0 兼容版本 安装 1.x.x 中最新版
~1.0.0 近似版本 安装 1.0.x 中最新版
file:../path 本地路径引用 引用本地模块
https://xxx.tgz 远程包引用 引用远程仓库的包

3.3 依赖的来源

HarmonyOS 的依赖可以来自以下来源：

  1. OHPM 仓库（默认）— https://repo.harmonyos.com/ohpm/
  2. 本地文件系统 — 通过 file: 协议引用
  3. Git 仓库 — 通过 git: 协议引用
  4. 远程 TGZ 包 — 通过 HTTP/HTTPS URL 引用
{
  "dependencies": {
    // OHPM 仓库
    "@ohos/hypium": "1.0.25",
    
    // 本地文件系统
    "@xiaoshiji/common": "file:../hsp_common",
    
    // Git 仓库
    "@xiaoshiji/utils": "git:https://gitcode.com/xiaoshiji/utils.git#v1.0.0",
    
    // 远程 TGZ 包
    "@xiaoshiji/analytics": "https://cdn.example.com/analytics-1.0.0.tgz"
  }
}

四、oh-package-lock.json5 锁文件

4.1 锁文件的作用

oh-package-lock.json5 是依赖的锁定文件，记录了所有依赖的精确版本和完整性校验信息：

// oh-package-lock.json5（部分内容）
{
  "lockfileVersion": "1.0",
  "packages": {
    "@ohos/hypium": {
      "version": "1.0.25",
      "resolved": "https://repo.harmonyos.com/ohpm/@ohos/hypium/-/1.0.25.tgz",
      "integrity": "sha512-xxxxxxxxxxxxxxxxxxxxx"
    },
    "@ohos/hamock": {
      "version": "1.0.0",
      "resolved": "https://repo.harmonyos.com/ohpm/@ohos/hamock/-/1.0.0.tgz",
      "integrity": "sha512-yyyyyyyyyyyyyyyyyyyy"
    }
  }
}

4.2 锁文件的管理

场景 锁文件的行为 建议
首次安装依赖 自动生成 oh-package-lock.json5 提交到版本控制
新增依赖 锁文件自动更新 提交更新后的锁文件
更新依赖版本 执行 ohpm update 后锁文件更新 提交更新后的锁文件
团队协作 拉取代码后执行 ohpm install 确保锁文件一致

提示：oh-package-lock.json5 必须提交到版本控制（Git），确保团队成员和 CI/CD 环境使用完全一致的依赖版本。

五、ohpm 包管理工具

5.1 常用命令

命令 说明 示例
ohpm init 初始化项目 ohpm init
ohpm install 安装所有依赖 ohpm install
ohpm install <package> 安装指定包 ohpm install @ohos/axios
ohpm install -D <package> 安装开发依赖 ohpm install -D @ohos/hypium
ohpm update 更新所有依赖 ohpm update
ohpm uninstall <package> 卸载指定包 ohpm uninstall @ohos/axios
ohpm list 列出所有依赖 ohpm list --depth=1

5.2 安装依赖的流程

ohpm install
    ↓
读取 oh-package.json5
    ↓
检查 oh-package-lock.json5
    ├── 存在 → 根据锁文件中的精确版本安装
    └── 不存在 → 从 OHPM 仓库获取最新兼容版本
    ↓
下载依赖到 oh_modules/ 目录
    ↓
生成更新后的 oh-package-lock.json5
    ↓
依赖安装完成

5.3 离线安装

在无网络环境的开发设备上，可以预先下载依赖包并离线安装：

# 在有网络的机器上预先下载
ohpm install --offline-prepare

# 复制 oh_modules/ 目录到无网络设备
# 在无网络设备上执行
ohpm install --offline

六、依赖管理的最佳实践

6.1 依赖版本锁定策略

场景 版本号格式 理由
三方库 精确版本 1.0.25 避免意外升级引入不兼容变更
内部库 精确版本 1.0.0 确保团队使用一致版本
开发依赖 精确版本 1.0.25 避免测试框架版本不一致
测试版库 精确版本 1.0.0-beta 明确表示非稳定版本

6.2 依赖冲突处理

当多个模块依赖同一库的不同版本时，可能发生依赖冲突：

// 模块 A 依赖 @ohos/axios 1.0.0
// 模块 B 依赖 @ohos/axios 2.0.0
// 冲突：无法同时安装两个版本

// 解决方案：在工程级 oh-package.json5 中统一版本
{
  "dependencies": {
    "@ohos/axios": "2.0.0"  // 强制使用 2.0.0
  }
}

6.3 依赖瘦身

策略 减少的包体积 实施方式
移除未使用的依赖 10%-30% 定期审查 oh-package.json5
使用 devDependencies 5%-10% 将测试框架移入开发依赖
使用 HSP 共享 15%-40% 将公共依赖抽取为 HSP
按需导入 5%-15% 仅导入需要的模块而非整个 Kit

七、oh_modules 目录结构

7.1 目录结构

安装依赖后，oh_modules 目录下存储了所有依赖包：

oh_modules/
├── .ohpm/
│   ├── @ohos+hamock@1.0.0/
│   │   └── oh_modules/
│   ├── @ohos+hypium@1.0.25/
│   │   └── oh_modules/
│   └── lock.json5
├── @ohos/
│   ├── hamock/
│   └── hypium/

7.2 .ohpm 目录的作用

.ohpm 目录是 OHPM 的内部缓存目录，存储了依赖包的元数据和锁信息：

// oh_modules/.ohpm/lock.json5
{
  "lockfileVersion": "1.0",
  "packages": {
    "@ohos/hypium": {
      "version": "1.0.25",
      "resolved": "https://repo.harmonyos.com/ohpm/@ohos/hypium/-/1.0.25.tgz"
    }
  }
}

八、依赖的发布与消费

8.1 发布到 OHPM 仓库

如果开发了自己的公共库，可以发布到 OHPM 仓库：

# 在库的根目录执行
ohpm publish

# 发布私有库到私有仓库
ohpm publish --registry https://private-repo.example.com/ohpm/

8.2 依赖的版本管理

oh-package.json5 中的 version 字段遵循语义化版本规范（SemVer）：

版本变更 示例 说明
主版本 1.0.0 → 2.0.0 不兼容的 API 变更
次版本 1.0.0 → 1.1.0 向下兼容的新功能
补丁版本 1.0.0 → 1.0.1 向下兼容的 Bug 修复

九、实际项目中的依赖演进

9.1 小事记当前的依赖状态

小事记当前依赖非常精简：

  • 运行时依赖：无（所有功能使用系统内置模块）
  • 开发依赖：@ohos/hypium（单元测试）、@ohos/hamock（Mock 测试）

9.2 依赖的演进路径

阶段 新增依赖 原因
阶段一（当前） 无运行时依赖 原型验证阶段，使用系统 API
阶段二 @ohos/axios 需要网络请求能力
阶段三 自定义 HSP 共享包 多模块共享代码
阶段四 三方 UI 组件库 提升开发效率

9.3 为小事记添加网络请求依赖

// 添加网络请求库
{
  "dependencies": {
    "@ohos/axios": "1.0.0"
  }
}

// 使用 axios 发送网络请求
import { axios } from '@ohos/axios';

async function fetchData() {
  try {
    const response = await axios.get('https://api.example.com/events');
    return response.data;
  } catch (err) {
    console.error(`请求失败: ${err.message}`);
    throw err;
  }
}

十、与 npm 和 Gradle 的对比

10.1 版本管理对比

对比维度 ohpm npm Gradle
配置文件 oh-package.json5 package.json build.gradle
锁文件 oh-package-lock.json5 package-lock.json 无（依赖解析）
依赖目录 oh_modules/ node_modules/ ~/.gradle/caches/
版本格式 ^1.0.0 ^1.0.0 1.0.0
包注册表 OHPM 仓库 npmjs.org Maven Central

10.2 依赖管理命令对比

操作 ohpm npm Gradle
初始化 ohpm init npm init （自动生成）
安装 ohpm install npm install gradle build
添加依赖 ohpm install <pkg> npm install <pkg> 编辑 build.gradle
更新 ohpm update npm update gradle refresh
卸载 ohpm uninstall <pkg> npm uninstall <pkg> 编辑 build.gradle

总结

本文从 xiaoshiji_ohos_app 项目的依赖配置文件出发，深入解析了 HarmonyOS 的 oh-package.json5 依赖管理机制。核心要点如下：

  1. 双层配置：工程级 oh-package.json5 管理全局依赖，模块级 oh-package.json5 管理模块特有依赖，两者形成层级结构
  2. @ohos 到 @kit 的演进：Kit 化模块按场景聚合功能，减少导入路径记忆成本，版本号统一管理
  3. 依赖类型：dependencies 为运行时依赖，devDependencies 为开发时依赖，两者的区别决定了是否包含在构建产物中
  4. 锁文件管理：oh-package-lock.json5 锁定精确版本，必须提交到版本控制，确保构建的一致性
  5. 版本锁定：推荐使用精确版本号，避免意外升级引入不兼容变更

至此，模块一（工程架构与 Stage 模型）的 8 篇文章全部完成。下一篇文章将进入模块二（UIAbility 与窗口管理），深入解析 UIAbility 的冷启动/热启动/后台启动三种场景与 launchParam 解析。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

# 后端
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙 ArkTS 实战：Water Intake Tracker 从喝水目标追踪到健康记录应用完整解析

avatar HarmonyOS开发者社区
cover

鸿蒙 ArkTS 实战：Split Bill Calculator 从AA账单到账单分摊应用完整解析

avatar HarmonyOS开发者社区
cover

鸿蒙 ArkTS 实战：Loan Repayment Estimator 从贷款月供估算到金融估算应用完整解析

avatar HarmonyOS开发者社区