ohpm 入门正确区分生产依赖、开发依赖与动态依赖专栏HarmonyOS 三方库适配实战3/30本篇目标让依赖出现在正确的生命周期而不是“哪里能装就写在哪里”。摘要HarmonyOS 工程的oh-package.json5可以声明dependencies、devDependencies和dynamicDependencies。三者不是三个随意选择的收纳盒生产依赖会参与编译和运行开发依赖只服务开发或测试动态依赖用于配合动态导入表达 HSP 依赖。本文通过一个本地 HAR 示例说明应该把依赖放在哪里、如何安装、怎样确认最终依赖树并分析把运行期库误放进开发依赖后的故障。适用范围与完成标志本文讨论模块或工程中的 ohpm 依赖声明不讨论 HSP 的完整部署流程。你需要能找到目标模块的oh-package.json5并知道哪个公开 API 会在正式代码中被调用。完成本篇后不只是“知道三个字段的中文名”还应能给每个直接依赖写出使用阶段、消费模块、实际导入点和验证命令。无法说明用途的依赖不应仅凭安装成功就保留。先记住一个判断问题不要先问“这个库叫什么”先问最终应用在目标设备执行公开功能时是否仍然需要这个依赖如果需要通常属于dependencies。如果只在开发、测试或构建辅助阶段使用属于devDependencies。如果它是通过动态导入按条件加载的 HSP才考虑dynamicDependencies。图 1依赖分类判断流程示意图。判断依据是发布产物中的运行责任。华为官方oh-package.json5文档明确说明生产依赖参与编译/运行开发依赖只能参与开发或测试动态依赖用于动态加载 HSP。三者的语义由交付方式和运行路径决定不由包体积或使用频率决定。示例给应用接入一个本地 HAR为了不假装某个远程示例包永远存在本篇使用本地 HAR 路径。假设适配库包名为demo/text-tool产物放在模块的libs/text-tool.har。它是教学包名不代表公共仓库中存在同名包。在消费模块的oh-package.json5中配置{ name: entry, version: 1.0.0, main: Index.ets, dependencies: { demo/text-tool: file:./libs/text-tool.har }, devDependencies: {} }然后在包含该oh-package.json5的正确目录安装依赖ohpminstall--allohpm list-d10官方安装 FAQ 特别提醒安装成功却看不到依赖时要先检查执行命令的目录。工程级和模块级都可能存在oh-package.json5安装产物与修改的配置文件必须对应。排查时同时记录命令所在目录、配置文件位置和ohpm --version。图 2本地复现实验记录。HAR 被ohpm解析并参与 HAP 构建设备调用仍待验证。给 HAR 准备一个可观察 API假设demo/text-tool的公开入口导出下面函数。文件位置应由库工程的入口配置决定例如Index.etsexportfunctionnormalizeSpaces(input:string):string{returninput.trim().replace(/\s/g, )}消费方通过包名导入而不是跨目录引用库内部源码import{normalizeSpaces}fromdemo/text-toolconstinput:string HarmonyOS third-party library constoutput:stringnormalizeSpaces(input)console.info(normalized${output})若该库的公开契约就是压缩连续空白预期输出可以写为normalizedHarmonyOS third-party library这里的输出是根据示例函数推导的预期值不是本轮设备日志。真实文章发布前应使用目标 SDK 编译并在模拟器或真机读取实际日志。dependencies运行时仍需要的生产依赖下面情况通常属于生产依赖应用或 HAR 的公开源码中直接import的工具库最终功能调用链上的组件、资源或 Native 库消费方构建和运行都必须解析的依赖。一个 HAR 如果公开 API 内部依赖另一个包也要根据实际交付关系正确声明不能指望消费方碰巧安装了相同依赖。devDependencies只服务开发与测试典型例子包括测试框架只在本地生成代码或检查格式的工具不进入最终运行调用链的开发辅助包。不要因为“这个包只有调试时才容易出错”就放进开发依赖。判断标准仍然是最终产物运行时是否需要它。下面是教学坐标不代表公共仓库中存在该包真正使用时要换成项目已经核对的测试工具及准确版本{ devDependencies: { demo/test-runner: 1.0.0 } }dynamicDependencies动态导入的 HSP 依赖动态依赖不是“偶尔使用的普通库”。官方添加依赖项文档说明dynamicDependencies仅限动态依赖 HSP 的场景。只有工程确实采用动态加载设计并且目标模块、产品和部署关系都满足要求时才使用。概念配置如下{ dynamicDependencies: { feature_chat: file:./libs/feature_chat.hsp } }在没有建立 HSP、动态加载和目标产品验证之前不要为了“提升启动速度”把普通 HAR 随意移到这里。故障复盘把运行库放入devDependencies假设entry在正式代码中导入demo/text-tool但配置写成{ devDependencies: { demo/text-tool: file:./libs/text-tool.har } }开发阶段可能因为缓存、其他模块或本地环境而暂时看不出问题但它的声明已经与实际用途矛盾。排查步骤是从报错导入反查实际调用链查看当前模块的oh-package.json5使用ohpm list -d 10检查最终依赖位置将真正的生产依赖移到dependencies重新安装并在干净环境构建消费模块记录锁文件和构建结果的变化。不要只通过复制oh_modules目录来掩盖错误声明。那会让本机暂时通过却让 CI 或新电脑失败。用干净环境确认修复调整依赖分类后至少比较以下证据检查调整前调整后oh-package.json5所在模块记录记录ohpm list -d 10中的节点保存保存锁文件是否变化是/否是/否目标模块构建失败/未知实际退出状态核心调用未执行/失败实际运行结果不要删除锁文件和安装目录来制造“干净”。如果确需清理先保存现场再依据当前 ohpm 文档选择保留锁文件的方式。一张可复用的依赖分类表问题是否正式源码是否直接或间接调用它倾向dependencies继续判断设备运行时是否必须携带它dependencies继续判断是否只用于测试、检查或开发辅助devDependencies继续判断是否通过动态 import 加载 HSPdynamicDependencies不要使用动态依赖本篇产物一个本地 HAR 的模块级依赖配置。一段公开入口与消费方调用代码。一套生产、开发和动态依赖的判断方法。进入下一篇前应该能运行ohpm list并指出每一个直接依赖为何出现在当前分类中。官方来源oh-package.json5用于三类依赖的定义、远程/本地 HAR/源码等依赖方式。访问日期2026-10-15。添加依赖项用于确认dynamicDependencies仅限动态依赖 HSP 的场景。访问日期2026-10-15。如何配置 oh-package.json5 动态依赖用于生产、开发、动态依赖的当前说明。访问日期2026-10-15。ohpm list用于查看直接和间接依赖。访问日期2026-10-15。ohpm 安装常见问题用于命令执行目录与安装产物的排查。访问日期2026-10-15。验证声明本文已于 2026-10-15 核对华为官方oh-package.json5、添加依赖项、动态依赖、ohpm list和安装 FAQ。实验工程已生成demo/text-tool1.0.0HAR将其作为 entry 的dependencies本地文件依赖安装ohpm list -d 10能读回该节点安装与列表命令退出码均为 0消费代码通过 API 22 目标 SDK 编译。demo/*仍是本地教学坐标不是公共仓库包本轮没有实际 HSP、模拟器或真机验证。