前言HarmonyOS 的依赖管理系统经历了从ohos原生模块到kitKit 化模块的重大演进。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模块名称在发布时使用entryversion模块版本遵循语义化版本1.0.0description模块描述Please describe the basic information.main入口文件路径未使用dependencies运行时依赖{}devDependencies开发时依赖ohos/hypium,ohos/hamock二、ohos 与 kit 的模块化演进2.1 演进背景从 API 12 开始HarmonyOS 引入了Kit 化模块kit/xxx来替代分散的ohos/xxx原生模块。这一变化的核心目的是按场景聚合— 将相关功能的模块聚合到同一个 Kit 中减少导入路径的记忆成本版本对齐— 同一 Kit 内的模块版本号一致避免版本兼容性问题按需引入— 开发者只需引入需要的 Kit系统自动按需加载模块2.2 ohos 时代 vs kit 时代对比维度ohos 时代kit 时代导入示例import { UIAbility } from ohos.ability.abilityLifecycleimport { 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.AbilityKitUIAbility、Want、Configuration、AbilityConstantohos.ability.abilityLifecycle、ohos.ability.wantkit.ArkUIwindow、UIContext、动画、弹框ohos.arkui.window、ohos.arkui.animationkit.CoreFileKit文件操作、备份扩展ohos.file.fs、ohos.file.backupkit.PerformanceAnalysisKithilog、hiTrace、性能监控ohos.hilog、ohos.hiTracekit.DataKitpreferences、relationalStoreohos.data.preferences、ohos.data.relationalStore提示在 API 12 及以上版本推荐使用kit/xxx方式导入。如果项目中仍在 importohos/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 的依赖可以来自以下来源OHPM 仓库默认—https://repo.harmonyos.com/ohpm/本地文件系统— 通过file:协议引用Git 仓库— 通过git:协议引用远程 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 initohpm install安装所有依赖ohpm installohpm install package安装指定包ohpm install ohos/axiosohpm install -D package安装开发依赖ohpm install -D ohos/hypiumohpm update更新所有依赖ohpm updateohpm uninstall package卸载指定包ohpm uninstall ohos/axiosohpm list列出所有依赖ohpm list --depth15.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使用devDependencies5%-10%将测试框架移入开发依赖使用 HSP 共享15%-40%将公共依赖抽取为 HSP按需导入5%-15%仅导入需要的模块而非整个 Kit七、oh_modules 目录结构7.1 目录结构安装依赖后oh_modules目录下存储了所有依赖包oh_modules/ ├── .ohpm/ │ ├── ohoshamock1.0.0/ │ │ └── oh_modules/ │ ├── ohoshypium1.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/hamockMock 测试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 版本管理对比对比维度ohpmnpmGradle配置文件oh-package.json5package.jsonbuild.gradle锁文件oh-package-lock.json5package-lock.json无依赖解析依赖目录oh_modules/node_modules/~/.gradle/caches/版本格式^1.0.0^1.0.01.0.0包注册表OHPM 仓库npmjs.orgMaven Central10.2 依赖管理命令对比操作ohpmnpmGradle初始化ohpm initnpm init自动生成安装ohpm installnpm installgradle build添加依赖ohpm install pkgnpm install pkg编辑build.gradle更新ohpm updatenpm updategradle refresh卸载ohpm uninstall pkgnpm uninstall pkg编辑build.gradle总结本文从xiaoshiji_ohos_app项目的依赖配置文件出发深入解析了 HarmonyOS 的oh-package.json5 依赖管理机制。核心要点如下双层配置工程级oh-package.json5管理全局依赖模块级oh-package.json5管理模块特有依赖两者形成层级结构ohos 到 kit 的演进Kit 化模块按场景聚合功能减少导入路径记忆成本版本号统一管理依赖类型dependencies为运行时依赖devDependencies为开发时依赖两者的区别决定了是否包含在构建产物中锁文件管理oh-package-lock.json5锁定精确版本必须提交到版本控制确保构建的一致性版本锁定推荐使用精确版本号避免意外升级引入不兼容变更至此模块一工程架构与 Stage 模型的 8 篇文章全部完成。下一篇文章将进入模块二UIAbility 与窗口管理深入解析 UIAbility 的冷启动/热启动/后台启动三种场景与launchParam解析。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源小事记项目源码xiaoshiji_ohos_app官方文档 - 包开发application-package-dev.md官方文档 - 包基础application-package-fundamentals.md官方文档 - 包结构application-package-structure-stage.md官方文档 - 包概览application-package-overview.md官方文档 - OHPM 使用ohpm-guide官方文档 - 应用模型application-models.md开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net
