依赖升级与锁文件兼容门：从解析差异到可恢复发布

把 foo 从 3.4 升到 3.5，PR 里却可能出现几百行 lockfile 变化。它们不一定是噪声：解析器可能替换了传递依赖，peer 条件选择了另一份包，可选原生模块在不同平台出现，或者包管理器版本重写了锁格式。编程 Agent 若只确认 package.json 中的一行，就无法证明实际安装树与生产兼容。

依赖升级的原子单元是 manifest、lockfile、包管理器版本和运行时矩阵。供应商风险与许可证由AI 供应链安全覆盖；本文专注“这次解析出了什么、在支持环境能否安装运行、失败时怎样完整恢复”。

本文命令固定在 Linux/GNU CI 容器（Bash、GNU coreutils、Git）执行；macOS/Windows runner 必须使用同一容器。

升级前冻结解析环境

仓库在 packageManager 字段固定 pnpm 版本，CI 使用 Corepack 激活，并从干净检出执行 frozen install。Node、操作系统、CPU 架构、registry 与配置摘要进入报告，认证信息只记录密钥版本。

mkdir -p .artifacts
node --version
corepack pnpm --version
sha256sum package.json pnpm-lock.yaml .npmrc
pnpm install --frozen-lockfile
pnpm --recursive --include-workspace-root list --depth Infinity --json \
  > .artifacts/tree-before.json

不要先删除 lockfile 再安装，这会把一次定向升级变成全图重新求解。先记录目标包的直接与传递路径、当前 peer 警告、安装脚本、许可证和原生二进制。升级命令只指向批准包与版本范围，再保存同样的树快照。

锁文件差分必须能解释

将变化分成目标包、必需传递闭包、peer 重新解析、平台可选项和无关变化。无关包版本变动、registry 域名变化、完整性摘要缺失或 lockfile 格式意外升级都阻断自动合并。若包管理器新版本必然重写格式，把工具升级拆成独立 PR，不能与业务依赖混在一起。

mkdir -p .artifacts
git diff -- package.json pnpm-lock.yaml
pnpm --recursive --include-workspace-root why target-package --json \
  > .artifacts/why-after.json
pnpm --recursive --include-workspace-root list --depth Infinity --json \
  > .artifacts/tree-after.json
node tools/compare-dependency-trees.mjs \
  .artifacts/tree-before.json .artifacts/tree-after.json

--recursive --include-workspace-root 同时覆盖全部 workspace 与根项目。比较器输出新增、删除和多版本共存节点，并标出每条引入路径。Agent 不得因为 diff 太大就重新生成 lockfile，也不得手工删除不理解的 peer 分支。npm 的 package-lock 与 pnpm lockfile 结构不同，工具必须解析其正式格式，不能用正则逐行猜测。

兼容门覆盖解析之外的行为

第一层是干净安装矩阵。在项目支持的最低与当前 Node 版本、Linux 生产架构和开发平台执行 frozen install；离线缓存验证可选，但不能替代从受控 registry 获取完整制品。所有环境要求同一 lockfile，不允许 CI 临时补写。

第二层检查 engines、peerDependencies、optionalDependencies 和安装脚本。peer 警告不是一律失败，但新增或变化必须有 owner 决策；原生模块要在目标 ABI 实际加载；跳过可选包后仍应满足声明的降级路径。安装脚本在无不必要网络和最小权限容器中执行，防止升级扩大供应链权限。

第三层运行编译、单元、契约和受影响集成测试。类型包的小版本也可能收紧声明，HTTP 客户端升级可能改变重试或默认超时，序列化库可能改变边界输出。编程 Agent 的改动验证门中的高风险规则照常生效，不能因“只有 lockfile”而跳过业务测试。

Monorepo 还要验证所有 workspace 的 peer 条件和重复版本，不只运行发起升级的包。使用Monorepo 工具链计算受影响项目，同时对共享构建插件、TypeScript、测试框架和代码生成器强制全工作区构建。

把门槛写成机器结果

一个可执行门禁可以要求：frozen install 在三种支持环境全部成功；未解释的传递变化为零；新增 peer 警告为零；高危漏洞与禁止许可证不增加；构建和契约测试通过；生产镜像体积变化不超过批准预算。安全数据库不可用时报告“未验证”并阻断，不把网络失败当成无漏洞。

CI 保存 package manager 版本、lockfile hash、安装树差分、构建产物 digest 和命令退出码。GitHub Actions CI/CD可承载矩阵，但缓存键必须包含操作系统、架构、Node、pnpm 与 lockfile hash；不能复用旧 node_modules 证明干净安装。

失败和回滚保持同一原子边界

安装失败先分类为解析冲突、registry、平台制品缺失或安装脚本问题。Agent 最多做受控的版本约束调整，禁止用 --force、--legacy-peer-deps、关闭脚本或取消 frozen 模式获得绿色。行为回归则保留最小样本，必要时换候选版本而非修改测试预期。

未发布升级直接撤销 manifest 与 lockfile 的同一提交。已经发布时，将流量切回旧镜像 digest，再 git revert <upgrade-sha>，从旧 lockfile 干净构建并核对产物 digest；不要在服务器手工安装旧包。若升级包含数据格式迁移，先确认旧版本仍能读取新数据，不能只回滚 JavaScript 依赖。

依赖升级的完成标准不是 CI 恰好绿色，而是目标变化可解释、所有支持环境能由同一锁文件重建、业务契约未退化，并且旧 manifest、lockfile 与镜像仍组成一条演练过的恢复路径。