【HarmonyOS NEXT】ohpm 安装依赖失败（@finclip 包找不到）问题复盘与解决方案

一、背景

我们项目需集成凡泰小程序，当前项目通过parameterFile配置了版本依赖保护（统一管理依赖版本），因此需在模块级oh-package.json5中手动声明@finclip/sdk依赖，执行ohpm install时出现@finclip/sdk包找不到的报错。

二、原因分析

1、依赖源不匹配：指定版本的@finclip/sdk不在当前配置的ohpm仓库（公司项目内部私仓+鸿蒙官方仓）中，且因开启了版本依赖保护（parameterFile）无法直接执行ohpm install命令，需按「确认 SDK 来源 → 配置仓库 / 离线包 → 同步参数文件」的流程解决

2、未利用项目级.ohpmrc：项目根目录的.ohpmrc是项目级依赖源配置文件（优先级高于全局配置），支持同时配置多个仓库源，但此前未正确利用其管理多源依赖。

三、具体实施操作

3.1、配置方式1：.ohpmrc配置registries

在项目根目录的.ohpmrc中正确配置多依赖源（逗号分隔），且中间无空格

这种方式是用「项目级多源配置」替代「全局单源切换」，从根本上解决 “切换仓库导致部分依赖拉取不到” 的问题。

配置后清除缓存并执行install拉取所有依赖

ohpm cache clean ohpm install

3.2、配置方式2：ohpm config set registr

步骤 1：确认 FinClip SDK 的依赖源

结论：并非本地引入SDK离线包，而是 FinClip 官方提供的私有 OHPM 仓库

步骤2：执行以下命令覆盖全局默认仓库为「凡泰仓」

ohpm config set registry https://ohpm.finogeeks.com/repos/ohpm/

3.3、补充说明

1、.ohpmrc 的优先级高于全局配置

只要项目根目录有.ohpmrc，OHPM 会优先使用其中的registries配置，完全忽略之前通过ohpm config set设置的全局registry—— 所以配置后，哪怕全局registry是旧值，也不影响项目拉取依赖。

2、配置后必须清除缓存

ohpm cache clean

3、方式建议

放弃 “全局 registry 反复切换” 的方式，优先建议项目根目录.ohpmrc配置多依赖源，这样一次配置即可满足所有依赖的拉取需求，无需再手动切换仓库

四、两种操作的差异