本篇聚焦依赖安装前的证据核对，不描述已经发生的真实线上故障。固定数据集来自自定义 JSON 夹具；文中版本和包名都是示例，未实际执行 ohpm install、DevEco 构建或仓库请求，工具的输出不能冒充官方 oh-package-lock.json5 的内部解析结果。

一、包声明没动，安装结果为什么值得再看一眼

有人以为只要 oh-package.json5 没改，今天和昨天构建出的依赖集合就必然相同。这个判断缺了一环：锁文件是否存在，以及它到底约束了哪些版本。官方 ohpm install 文档说明，安装会依据声明文件定义的依赖关系进行处理；存在 oh-package-lock.json5 时，安装受锁定版本影响。官方 ohpm clean 的说明也提醒，默认清理可能删除锁文件，而 --keep-lockfile 会保留相关锁定文件。两条信息放到日常工程里，已经足够说明“清理一下再装”不是没有语义的操作。

本轮不试图讲所有依赖解析器，也不假定任何三方包都能复现漂移。把范围缩到一个实际可管理的交付动作：在进入重新安装或构建前，检查我们自己保存的“基线证据”和“候选快照”是否一致。基线由一次已经确认的工程状态生成，候选值来自即将使用的计划。若锁文件缺失、锁定版本不同或包来源发生变化，就停下来要求人工解释，而不是让 CI 悄悄恢复为绿色。

Demo 名叫 LockSnapshotGate，页面分别为 DepGatePage.ets 与 DepAuditPage.ets，检查入口 tools/audit-lock.mjs。样例任务编号 LCK-1010-25，数据集 ohpm_deps_07，合计七个示例包。预期四个通过、三个拦截：LOCK_MISSING 一项、VERSION_DRIFT 一项、SOURCE_DRIFT 一项。最终业务状态 LOCK_HOLD，实际安装、编译与发布验证都保留 NOT_RUN。这些字段由我们定义，不是 ohpm 官方状态枚举。

这张封面把问题画成一张受到保护的依赖清单。与普通“如何发布 HAR”不同，本篇不检查归档根目录、许可证文本、README 或打包签名，也不写三方库中心仓发布流程。这里唯一要回答的问题是：在不运行安装的前提下，能不能发现本次候选快照已经偏离审核过的锁定证据？

二、锁文件是安装决策输入，不是随手可以重建的缓存

根据华为 2026 年 10 月 8 日更新的 ohpm install 文档，ohpm install 在无指定包名时根据当前的 oh-package.json5 解析依赖，若存在锁文件则受锁定版本影响。这只说明工具行为的基本边界，不能推导每一版 ohpm 都以相同方式处理仓库缓存或复杂 overrides。我们的检查应围绕“可观察的安装输入”设计，不应把对工具内部文件结构的猜测写死进脚本。

另一个官方入口 oh-package.json5 明确区分工程级和模块级配置，并说明 dependencies、devDependencies、dynamicDependencies 的不同含义。工程级 overrides 和模块级依赖会一起影响最终结果。若检查器只读 entry 模块的一份声明，遗漏工程级策略，就可能把真正的变化看成无关细节。当前夹具为了可复核，只保留包名、批准版本、候选版本、来源标识和锁定存在性五类字段，并明确把它称为“业务侧快照”。

所以，这个 Demo 没有宣称自己能解析任何真实版本的 oh-package-lock.json5。更实际的做法是在可信安装后，通过团队确认的工具输出或 CI 过程生成归一化基线，再用自定义 JSON 保存核验信息。为避免把测试数据伪装成系统真相，示例包统一采用 @demo/ 命名空间，它们不是需要读者联网安装的真实依赖。真实接入必须明确快照如何从实际工程采集，并给采集工具本身做版本管理。

七个包的固定结果分别是：@demo/ui、@demo/codec、@demo/forms、@demo/cache 四项通过；@demo/theme 缺少锁定记录；@demo/plot 从基线版本 2.9.0 漂移到候选 3.0.1；@demo/media 的来源标识发生变化。三种异常性质不同，修复操作不能一律写成“删掉 oh_modules 再试”。那样也许会得到能安装的结果，却失去解释依赖为什么改变的证据。

三、先定下快照契约，工具才有一致的比较对象

业务夹具采用结构简单的 JSON 数组。每一行包含 name、baselineVersion、currentVersion、baselineSource、currentSource、lockPresent。所有字段都由构建准备流程生成，不能让提交者在同一份候选文件里同时自由修改“基线”和“候选”，否则校验形同虚设。示例为了展示比较逻辑，把两侧放在一个对象中；生产环境应把受保护基线单独保存并限制写权限。

源信息只存规范化标识，例如“central-repo”或“private-mirror”，而不是在日志里打印可能含身份令牌的完整仓库 URL。版本比较采用字符串完全一致，目的就是阻止未经批准的漂移，不是代替 semver 判断兼容性。应用能够运行在新版并不等于供应链允许它在未登记的情况下自动变更。项目可以设计升级审批流，但审批本身必须是一条可追踪的记录，而非在检测失败时直接把基线覆盖成当前值。

// tools/audit-lock.mjs：业务快照结构及判定逻辑（不是 ohpm 内部锁格式）
export function decideDependency(dep) {
  if (dep.lockPresent !== true) return 'LOCK_MISSING';
  if (dep.currentVersion !== dep.baselineVersion) return 'VERSION_DRIFT';
  if (dep.currentSource !== dep.baselineSource) return 'SOURCE_DRIFT';
  return 'PASS';
}

export function auditDependencies(deps) {
  const results = deps.map(dep => ({ name: dep.name, result: decideDependency(dep) }));
  const counts = { PASS: 0, LOCK_MISSING: 0, VERSION_DRIFT: 0, SOURCE_DRIFT: 0 };
  for (const row of results) counts[row.result]++;
  const blocked = results.length - counts.PASS;
  return { taskId: 'LCK-1010-25', total: results.length,
    passed: counts.PASS, blocked, counts,
    state: blocked === 0 ? 'LOCK_READY' : 'LOCK_HOLD', results };
}

这段函数的返回值是一个完整报告，而不是在遇到第一处错误就退出。这样在七项中发现三个问题时，开发人员只需一次审计就能知道该先补锁、核版本还是查来源。错误判定采用固定优先级：锁记录不存在时不再继续给该项附加版本冲突；版本不一致时也不再叠加来源错误。这样保证每个包只有一个主因，报告中“通过四、阻断三”才能与细项相加一致。

此处还应检查 name 是否重复。如果候选快照中出现同名不同版本两条记录，直接按数组计数可能把一个包当成两个包。正式脚本应在比较前构建键集合，遇到重复键直接标记数据源非法，并停止发布门禁，而不是选择先出现的一条覆盖后一条。为了避免演示统计与文章契约发生冲突，本批七条固定输入没有重复包名；对重复项的拒绝是后续扩展用例，不算进本轮三个问题中。

四、用可控夹具把七条差异固定下来

与其在文章中贴出一段假装来自真实终端的安装日志，不如展示业务快照如何得到七项结果。下面这些名称和版本都属于教学夹具，它们不指向真实 OpenHarmony 三方库中心仓。为了突出异常门禁，不涉及实际依赖下载、解包执行或私有缓存扫描。数据提供四个稳定案例与三个拒绝案例，并且让每条原因只出现一次。

// 固定输入，可以保存为 fixtures/deps-current.json 后在Node.js中读取
const same = (name, version, source = 'central-repo') => ({
  name, baselineVersion: version, currentVersion: version,
  baselineSource: source, currentSource: source, lockPresent: true
});
export const dependencies = [
  same('@demo/ui', '1.2.0'),
  same('@demo/codec', '2.1.0'),
  { ...same('@demo/theme', '0.9.5'), lockPresent: false },
  same('@demo/forms', '1.0.3'),
  { ...same('@demo/plot', '2.9.0'), currentVersion: '3.0.1' },
  same('@demo/cache', '1.1.0'),
  { ...same('@demo/media', '2.0.0'), currentSource: 'private-mirror' }
];
// 用上节的 auditDependencies(dependencies) 得到 PASS=4, blocked=3。

这里存在两种不同层面的“版本”：一个是三方包本身的版本，另一个是生成依赖快照的检查器版本。长期运行时，检查器升级也可能改变源标识归一化规则。建议在报告头加入 snapshotSchema 和 auditToolVersion，并在两个字段不兼容时先停止对比，而不是把无法解释的差异算作真实包漂移。当前固定示例没有模拟模式迁移，因此把这一点列为上线前的补充验收项。

图片应当能看出具体问题：@demo/theme 对应 LOCK_MISSING，@demo/plot 对应 VERSION_DRIFT，@demo/media 对应 SOURCE_DRIFT。读者若发现列表里的问题数量与汇总不一致，应把素材视为演示错误，不应修改业务逻辑迁就图片。本篇固定任务编号始终是 LCK-1010-25，数据集 ohpm_deps_07，状态 LOCK_HOLD，便于截图、测试和代码之间逐项交叉检查。

图02展示白色 IDE 演示布局：左侧项目树、中间自定义 audit-lock.mjs、右侧检查预览、下方固定输入日志。它不是 DevEco 编译截屏，也没有真正运行 ohpm install。如果后续加入真实 CI 截图，需在标题、图注和校验记录中明确区分“演示”和“运行证据”，不能只因为界面长得像 IDE 就把测试结论升级。

五、状态要说明能否继续，而不只是哪里出了红色

LOCK_HOLD 表示当前快照有未经批准的差异，不允许作为“基线已确认”的候选进入正式构建。它不是系统安装失败，也不是说明这三个库有安全漏洞，更不是华为应用市场审核结论。界面可以让团队看到四项通过、三项阻断，但下一步应当是审查版本和来源，决定回退还是登记升级，而非一键修复后静默继续。

在实际项目里，开发人员可能需要升级 @demo/plot 所对应的真实组件；允许它升级的条件，是提交明确的版本变更说明和审核后的基线快照。SOURCE_DRIFT 更敏感一些，因为即便版本号相同，来源从公共仓库改为私有镜像，也可能意味着构建内容不可复现。当前样例只比对来源字符串，没有下载并计算包内容哈希，所以还不能检测“同名同版本但实际字节已变”的情况。

LOCK_MISSING 也不一定意味着有人恶意篡改。一次没有保留锁文件的清理、一段错误的 CI 工作目录、或者某个模块第一次引入，都可能产生同类结果。工程判断首先要弄清楚是谁、在什么路径、使用哪个 ohpm 版本生成了候选快照。否则只是把异常自动归类，没有让排查成本真正下降。诊断页保留包名、批准版本、当前版本和来源差异，就是为了让工程师可以回到明确的构建输入，而不是盯着一个抽象错误码猜原因。

图03用纯手机布局展示四绿三红的对账结果。页面中的“依赖锁文件对账”是应用自行实现的运维可视化，不是系统包管理器功能。实际移动端一般不会重新安装三方 HAR；将该页面视为展示离线审核报告的客户端即可。该场景和“终端执行 ohpm”必须分开，原因与平台定位有关：ohpm 是构建期的包管理工具，不是让 App 自己下载安装源码的运行时 API。

六、CI报告先落盘，失败也要留下可追查证据

工具化后的价值不只在于 exit code。提交被拦截时，必须留下一份可以复核的报告，包含输入摘要、检查器版本、每个包的决策结果、退出状态和执行时间。当前示例可以安全地在 Node.js 环境中运行，因为只读自定义 JSON 字段，使用的也是 node:fs/promises，没有碰 ohpm 内部格式。真正进入工程后，应把报告保存在构建日志和制品附件中，但敏感地址、访问令牌和认证配置要做脱敏。

// tools/report-gate.mjs（只写本地审计报告，不执行安装）
import { mkdir, writeFile, rename } from 'node:fs/promises';
import { join } from 'node:path';

export async function publishReport(result, dir = '.audit') {
  await mkdir(dir, { recursive: true });
  const finalPath = join(dir, 'LCK-1010-25.json');
  const tempPath = join(dir, 'LCK-1010-25.tmp');
  await writeFile(tempPath, JSON.stringify({
    schema: 'fixture-audit-v1', dataset: 'ohpm_deps_07',
    ...result, ohpmInstall: 'NOT_RUN', build: 'NOT_RUN'
  }, null, 2), 'utf8');
  await rename(tempPath, finalPath);
  return { finalPath, exitCode: result.blocked > 0 ? 2 : 0 };
}

同目录写临时文件再重命名，可以减少读取方看到一半 JSON 的概率。但不能据此宣称所有文件系统上都具备完全相同的原子性，更不能把这一技术称为依赖包事务安全。报告落盘失败时应该直接使构建准备流程失败，并保留 stderr；不能因为业务规则判定 PASS，就忽略日志缺失继续发布。审计的核心是可追溯的决定，没有审计证据的“通过”很难对团队负责。

脚本退出码 2 仅是本项目的约定，ohpm 本身不一定以相同编码报告这种问题。将它接入 CI 时，应在独立步骤运行“业务侧依赖快照核对”，随后才让正式工具链安装、构建。对比阶段与 ohpm install 的执行顺序要固定，不能先让安装器把锁文件重建，再将“本次生成的锁”当成“历史已批准的锁”去比较。那相当于先消除证据，再证明没有差异。

七、日志与差异页怎么才算能定位问题

诊断时间线采用 19:20:10 LOAD、19:20:11 COMPARE、19:20:12 LOCK_MISSING、19:20:13 VERSION_DRIFT、19:20:14 SOURCE_DRIFT、19:20:15 LOCK_HOLD 六个固定步骤。日志只描述规则流程，不假装已经连接中心仓。移动详情页会把 @demo/theme、@demo/plot 和 @demo/media 展开成三条差异证据，其余四条显示通过。

看问题时，先看锁定记录是否存在，再看是否未批准升级，然后看来源标识是否变化。对“版本 2.9.0 → 3.0.1”这种很容易被自动升级掩盖的差异，记录原值与候选值比单纯写 VERSION_DRIFT 更有用。对“来源变化”则应该追问镜像配置是谁修改的、是否受信任、同版本内容是否已重新校验，而不是仅因为来源在白名单内就直接通过。

真实生产环境还要留意并发写。多个 CI 任务如果共用同一个基线文件和报告路径，最后写入的任务可能覆盖另一个任务的结论。应按提交 SHA 或构建任务号隔离报告目录，给正式基线使用只读权限，并在批准升级时建立新的基线版本。当前任务号 LCK-1010-25 只适用于本轮样例，不应直接当成跨多次真实构建的唯一键。

八、从清理命令回到可复现构建的完整边界

华为官方的 ohpm clean 指南提醒，默认清理会移除模块安装产物以及相关锁文件，而 --keep-lockfile 可保留锁文件；ohpm install 会受现有锁定版本影响。正因为如此，团队应该把“清理工程”拆成两个有名字的动作：一种只清安装目录、保留锁证据；另一种主动重建锁定结果，并进入升级审批。这不仅方便提速，也让问题发生时有一条可靠的时间线。

但离线准入不是万能药。它没有替代 ohpm 官方解析器，没有验证真实 HAR 的字节完整性，也没有解决不同工具版本对依赖图的兼容性差异。它能够确定的，是给定的两份业务快照是否满足当前政策。当源仓不可访问、锁文件格式变化、缓存条目污染、签名配置不一致时，仍要回到真实工具链逐层诊断。将这些风险压缩成一个绿色图标，会给团队错误的确定感。

这次在七条示例上得到明确结果：LCK-1010-25，通过四条、阻断三条，各类阻断原因一次，状态 LOCK_HOLD；ohpmInstall=NOT_RUN、build=NOT_RUN、release=NOT_RUN。从图文交付的角度，这些数字要从封面到 IDE 示意、手机主界面、差异诊断保持相同。若某张图把三种阻断写成两种，不能修改统计定义去迁就视觉，应该明确返工。

九、工具应该让版本变更有出处

一个好的依赖核对工具不是为了把每次升级都挡住，而是为了让升级有出处。批准升级后，基线应随代码一起审阅并更新；未经批准的版本或来源变化则及时拦截。它不负责替团队判断一款库是否“安全”，只负责保证当前构建候选是否仍然对应那个被批准的依赖集合。把责任边界限定清楚，才不会在发生交付问题时反过来质疑工具“为什么没发现一切”。

后续可以分层扩展：先接上受信任工具输出生成快照，再逐渐纳入依赖子图差异、制品哈希和构建工具版本比对。每加一层，都应先设计对应的固定夹具、错误原因和回滚流程。没有被验证的层要明确写“待接入”，不应在技术文章中用“已经支持”来填空。这也是本轮将真实 ohpm 调用留在 NOT_RUN 的原因：示例想讲清楚准入原则，而不是编造一条不存在的发布成功记录。

如果维护者发现源码声明和快照完全一致，仍应检查两个文件究竟是否来自同一提交。把昨天的基线和今天的候选放在同一个目录里，人为覆盖风险很高。建议生成报告时记录基线提交号、候选提交号、构建环境标识和检查器自身版本，随后通过 CI 日志绑定这些信息。这些字段不是安全认证，但能让下次重新执行时知道应当取哪一份输入。

对依赖源做字符串比较也有盲区。比如两个源地址经过重定向最终指向同一仓库，严格比较会误报；反过来，标签未变而仓库内容被替换，简单字符串比较又会漏报。应在真实接入阶段把来源身份、可验证摘要和组织内可信源策略分别存储。当前样例只演示来源标识变化的阻断，不声称检测了仓库投毒或制品供应链攻击，也不鼓励把私有凭证直接加入报告。

还要给“批准升级”留出可见路径。当依赖升到新版本并通过单元测试后，负责人应同时审核业务功能变化、许可证变化与新快照，把批准动作和有效期记录下来，再生成下一版基线。只修改 baselineVersion 让颜色变绿，不是工程上的解决方案。任何绕过报告的人工操作都应在交付流水线留下说明，而不能成为团队默认的静默修复办法。

最后的验收应从两次独立运行比较开始：同一份夹具多次执行，输出结果的排序和原因统计应一致；轻微调换 JSON 数组顺序也不能改变被接受包集合。报告中可以记录产生时间，但计算差异的核心摘要应排除易变时间字段，避免把同样的内容误判成变化。此次脚本提供了判定与落盘的参考结构，还没有完整的跨操作系统文件语义和并发 CI 测试，这些都需要进入真实项目后补齐。

官方资料核查：华为 ohpm install（更新于 2026-10-08）https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/ide-hmos-ohpm-install ；oh-package.json5 配置与依赖类型（更新于 2026-10-08）https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-hmos-oh-package-json5 ；ohpm clean --keep-lockfile https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-ohpm-clean-V5 。本文脚本仅解析自定义 JSON 夹具，不声称上述官方锁文件存在本文自定义字段。