一、配置文件每一项都合理，放在一起却安装不了

一个HarmonyOS工程在迁入新的三方HAR后，可能同时需要做两件事：把上游不再适用的子依赖排除掉，又临时重写另一个库的依赖关系。两项修改分别打开看都说得通，提交到同一份工程级 oh-package.json5 后却触发冲突。团队最容易误判的地方，是觉得“排除”和“重写”属于两个工具能力，彼此互不影响。

本篇聚焦一个非常具体的约束：工程级 exclusions 和 overrideDependencyMap 不允许出现相同的键。华为开发者官方的 oh-package.json5 文档明确说明，同键会引起配置冲突并中断程序。与讨论抽象的版本锁定、依赖分类不同，这里只做一条可确定的静态规则，把错误尽量挡在CI安装依赖之前，不去猜测ohpm内部版本决策的实现。

我们给这个脚本取名 RuleCollision，构造一份含有两条 exclusions 规则和一条 overrideDependencyMap 规则的项目配置，双方共同声明 @acme/vision。预期审计结果为 EXCLUSIONS 2、OVERRIDES 1、CONFLICTS 1、BLOCKED，脚本退出码设为 2。

本例适合在代码评审或合并请求流水线里作为快速守门员。它不安装依赖，也不修改锁文件。官方建议把 oh-package-lock.json5 加入版本控制，同时不建议其他分析工具直接读取锁文件；因此脚本的输入应是工程级清单和显式配置，不能偷偷改用锁文件结构来推断结果。

二、为什么必须限定为工程级规则

oh-package.json5 分工程级和模块级。生产依赖、开发依赖、动态HSP依赖由不同字段承担，工程级则包含诸如 overrides、exclusions、overrideDependencyMap 的全局干预配置。exclusions 的作用是移除远程依赖或本地文件依赖的子依赖，对源码依赖无效；它只能作用于相应生产和动态依赖范围。overrideDependencyMap 则用指定文件替换某个目标依赖节点的直接子依赖关系。两者不是简单字符串别名。

官方约束还带着一些容易漏看的细节。例如，overrideDependencyMap 的键可以带具体版本号，指定版本必须符合要求；目标文件若使用相对路径，还涉及 .ohpmrc 中的路径解释开关。本文的静态检查只做原始键完全相等的判断，这是官方明确禁止的最小闭环。@acme/vision 与 @acme/vision@1.0.0 并不是相同字符串，不应被本脚本擅自判为官方定义的同键冲突。至于这两种规则是否会在语义上影响同一个实际节点，需要留给ohpm解析和人工审查。

第一段代码读取工程级JSON5配置。因为JSON5允许注释和尾随逗号，不能用原生 JSON.parse 强行读取。这里在Node.js开发工具脚本中使用明确声明的开源 json5 包；如果本地没有安装，应先把它固定为脚本的开发态依赖，不能假装Node.js内置了这个模块。

import fs from 'node:fs/promises';
import JSON5 from 'json5';

async function loadProjectManifest(file) {
const raw = await fs.readFile(file, 'utf8');
const doc = JSON5.parse(raw);
if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
throw new Error('INVALID_PROJECT_MANIFEST');
}
return doc;
}

fs.readFile 负责读取原始文本，JSON5.parse 负责语法解析，脚本不对注释做自行正则剥离，以免破坏引号内的内容。文件路径由CI明确提供，异常包括文件不存在、权限不足和配置语法不合法，任何一种都应中止本次检查并反馈准确原因。

三、配置冲突不能靠覆盖顺序碰运气

示例清单如下：工程级 exclusions 包含 @acme/vision 与 @acme/geo 两个键；overrideDependencyMap 包含 @acme/vision 一个键，值是构建机上示例性的绝对路径 /workspace/ci/dep-vision.json5。准确的配置文件可以随着团队机器路径变化；判断依据始终是两个对象的键集合，不依赖它们的值。

为了让冲突报告稳定，第二段代码先校验字段形状，再对键集合做精确交集。数组和数字等错误类型明确拒绝；排序保证不同Node.js运行环境或开发者改动顺序时，输出不至于无意义地漂移。既然这个脚本宣称是门禁，就应当输出确定的错误分类，而不是在日志里写一句模糊的“安装失败”。

function record(value, label) {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw new Error(`${label}_NOT_OBJECT`);
}
return value;
}

function findCollisions(doc) {
const exclusions = record(doc.exclusions ?? {}, 'EXCLUSIONS');
const rewrites = record(doc.overrideDependencyMap ?? {}, 'OVERRIDES');
for (const [key, items] of Object.entries(exclusions)) {
if (!Array.isArray(items) || !items.every(v => typeof v === 'string')) {
throw new Error(`BAD_EXCLUSION:${key}`);
}
}
const rewriteKeys = new Set(Object.keys(rewrites));
const conflicts = Object.keys(exclusions)
.filter(key => rewriteKeys.has(key)).sort();
return { exclusions: Object.keys(exclusions).length,
overrides: rewriteKeys.size, conflicts };
}

这里的 Set 是Node.js标准JavaScript集合，并非ohpm提供的SDK。record 只是最小的字段类型守卫：它可以拦住明显损坏的数据，但没有复刻官方所有配置约束。比如某个 exclusions 键所指的是源码依赖，或重写文件路径在另一台机器上不可读，都属于后续审查内容。碰到同键冲突时，正确处理方式是让开发者决定保留排除还是保留重写规则，而不是让脚本擅自删除一个字段并继续构建。

四、从审计结果到流水线退出码

把检查写在项目脚本里，还有一个优势：终态不会被大量普通日志淹没。示例数据使用 @acme/vision 冲突键，输出可以逐项核对。BLOCKED 是本地策略状态，exitCode=2 是本文约定的CI退出规则。在真实工程中，入口脚本应从CI工作目录获得绝对配置路径，并限制参数来源；这里采用固定路径表达清楚流程。

第三段实现最小命令行入口，先打印统计，再打印冲突键。对于脚本自身的文件或语法错误，另行使用退出码 3，这样排查者可以区分配置冲突与脚本不可用。

const demoManifest = {
exclusions: {
'@acme/vision': ['@acme/log'],
'@acme/geo': ['@acme/cache']
},
overrideDependencyMap: {
'@acme/vision': '/workspace/ci/dep-vision.json5'
}
};

try {
const report = findCollisions(demoManifest);
const state = report.conflicts.length ? 'BLOCKED' : 'READY';
console.info(`RuleCollision EXCLUSIONS ${report.exclusions}`);
console.info(`RuleCollision OVERRIDES ${report.overrides}`);
console.info(`RuleCollision CONFLICTS ${report.conflicts.length}`);
report.conflicts.forEach(key => console.error(`CONFLICT ${key}`));
console.info(`RuleCollision ${state}`);
if (report.conflicts.length) process.exitCode = 2;
} catch (error) {
console.error(`RuleCollision SCRIPT_ERROR ${String(error)}`);
process.exitCode = 3;
}

此段为了展示固定结果直接把构造对象传入检查器，真实的流水线入口应改为 const doc = await loadProjectManifest(projectFile)。这两个入口不可同时在一个脚本中执行而产生两次报告。由此构造输入可以推导出：排除规则数为2、重写规则数为1、冲突键数为1，终态BLOCKED，退出码为2。CI应把这个退出码作为失败条件；如果只是脚本本地示例，可在单独进程中观察结果，不要把错误吞掉后返回成功。

五、别把规则审计包装成发布审核通过

手机页面可以设计成审计结果的只读看板：上方列出 RuleCollision · RuleCollision，中部依次列出 EXCLUSIONS 2、OVERRIDES 1、CONFLICTS 1，底部强调冲突键 @acme/vision 与 BLOCKED。需要特别说明的是，手机图只是同一结果的预设信息设计。Node.js脚本实际在开发/构建环境运行，

上线前还需排查四类问题。第一，确认 exclusions 与 overrideDependencyMap 确实写在工程级，而不是模块级清单中；后者可能不按预期生效。第二，检查重写文件是否存在，内部字段是否属于允许的三类依赖节点，以及相对路径开关是否配置。第三，检查项目是否启用了 .ohpmrc 的配置覆盖机制：如果CI运行时实际使用了覆盖后的项目清单，检测原始文件可能漏报。第四，在真正执行 ohpm install 之前确认依赖源与权限可靠，脚本并未验证远端包存在或依赖图无循环。

尽量不要把所有错误都折叠成一个布尔值。门禁日志应该列出规则键、配置来源与错误种类，但不要打印仓库密钥、鉴权令牌或私仓URL里的敏感参数。若团队需要归档，可以仅记录文件相对标识和冲突键，不把完整开发者本机绝对路径上传到公共CI日志。相同的审计可以在提交前与CI复用，但应确保Node版本、JSON5解析依赖和规则策略版本一致。

六、结论与参考资料

这篇的落点是一个很小的工程事实：配置文件能解析，不等于多个高级规则可以并存。通过读取工程级 oh-package.json5、精确检查两个键集合是否相交、用不同退出码区分规则冲突与脚本故障，团队就能在安装依赖前得到一份明确的诊断报告。这种检查不会代替ohpm，更不会替代HarmonyOS应用上架审核；它的价值是缩短配置错误到可定位原因之间的距离。

参考资料：华为开发者《oh-package.json5》（工程级字段、exclusions与overrideDependencyMap约束） https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hmos-oh-package-json5%EF%BC%8C%E3%80%8A%E6%B7%BB%E5%8A%A0%E4%BE%9D%E8%B5%96%E9%A1%B9%E3%80%8B https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/ide-hmos-hvigor-dependencies%E3%80%82%E6%9C%AC%E6%96%87%E7%9A%84Node.js%E4%BB%A3%E7%A0%81%E6%98%AF%E5%BC%80%E5%8F%91%E4%BE%A7%E8%BE%85%E5%8A%A9%E5%AE%A1%E8%AE%A1%EF%BC%8C%E5%AE%9E%E9%99%85%E7%94%9F%E4%BA%A7%E6%9E%84%E5%BB%BA%E4%BB%8D%E5%BA%94%E4%BB%A5%E5%AF%B9%E5%BA%94SDK%E4%B8%8Eohpm%E7%89%88%E6%9C%AC%E7%9A%84%E5%AE%98%E6%96%B9%E8%A1%8C%E4%B8%BA%E4%B8%BA%E5%87%86%EF%BC%9B