2.4 幽灵依赖现场还原与根治
2.4 幽灵依赖现场还原与根治
本节摘要：幽灵依赖指代码引入了清单未声明的包——它因提升规则而"恰好可用"，也因上游一次内部调整而"突然消失"。本节还原一桩完整事故：从本地构建通过、CI 离奇失败，到定位出那条未声明的引入，再到给出从应急到根治的处置阶梯。这是第二章机制章节的收口之作：2.2 的宽松语义与 2.3 的提升规则在此相乘成灾，根治手段也直接对应第五章的隔离布局方案。
事故档案：一次深夜构建失败
背景交代：某团队的 Web 应用已稳定迭代一年多，工具函数集中在 utils 模块里。某天深夜，一次例行合并后 CI 突然失败，而所有开发者本地构建全部通过。失败信息只有一行模块找不到：
ERROR in ./src/utils/format.ts Module not found: Error: Can't resolve 'date-fns' in '/project/src/utils'
更诡异的是回溯历史：utils 里的格式化函数一个月前就写了，一直构建正常；这期间 date-fns 从未出现在 package.json 里，团队也确实没人记得装过它。
勘验过程：三步锁定成因为提升
排查从"本地说谎"开始——本地能过而 CI 挂，说明两边依赖环境不同。第一步，核对清单：
$ grep "date-fns" package.json （无输出 —— 清单里根本没有） $ ls node_modules | grep date-fns date-fns # 目录却在！
清单没有、目录却在，提升机制的指纹已经出现。第二步，追它是怎么进来的：
$ npm explain date-fns myapp@1.0.0 `-- chart-kit@3.2.0 `-- date-fns@2.30.0 # 来自图表库 chart-kit 的内部依赖
真相拼齐了：chart-kit 内部用 date-fns 做日期处理，被提升到顶层；一个月前写格式化函数时，编辑器自动补全"好心"地给出了 date-fns，开发者顺手引入——本地从此可用，而这条依赖从未写进清单。第三步，解释"为什么偏偏今天爆"：chart-kit 当天发布了新版本，团队锁文件里的 chart-kit 3.2.0 被依赖更新机器人推进到 3.3.0，而 3.3.0 把日期处理换成了自研函数，不再依赖 date-fns。于是顶层目录里 date-fns 消失，那条幽灵引入当场现形。
图 2-4 幽灵依赖的形成链路与断裂点
处置阶梯：从应急到根治
事故现场的最快恢复是"有什么用什么"——把 date-fns 正式装进清单，立即止血：
$ npm install date-fns # 或者若决定改用其他方案，把引入换成清单里已有的包
一行命令让依赖关系回归"你声明、你负责"的正轨，CI 立刻恢复。但止血不等于根治——同类事故的入口还在。根治按强度分三档：
第一档：规则拦截。 在代码检查工具里引入"未声明依赖禁入"规则，让引入清单外的包直接报错。这是成本最低的长期防线，几乎任何规模的项目都该配上。
第二档：清单核对进流水线。 安装后运行依赖一致性检查，凡是被引入但未被声明的包即在 CI 阶段失败，把防线前移到合并之前。
第三档：换严格布局的工具链。 pnpm 的隔离布局让每个包只能看到自己声明的依赖，幽灵包物理上不可引入；Yarn 的免安装模式同样以严格为卖点。这是釜底抽薪，但牵动整个团队工具链，适合作为技术债专项推进——两套方案的机制勘验在第五章 5.2 与第七章横评里展开。
应急靠加装，短期靠规则，长期靠隔离——三档处置对应三种时间尺度，按团队能承受的改动半径选。
变式推演：同样链路的三种变形
同一形成链路换个条件，事故形态就变。变式一：等价替换。 上游没删依赖，只是把 date-fns 换成了 dayjs，顶层同时存在两个日期库——不报错，但两个功能重叠的库一起被打进产物，体积悄然膨胀。这类"无报警的幽灵"更常见也更难察觉，产物分析工具是唯一可靠的探针。变式二：版本漂移。 上游没删 date-fns，只是升了大版本，顶层 date-fns 从 1.x 变 2.x，幽灵引入的代码开始行为异常——比找不到包更阴险，因为它"还在"，只是不是你认识的那个它。变式三：测试环境独有。 某依赖只在开发工具链里被提升，生产构建裁剪掉了它，本地开发能跑、打包后运行时报错——排查方向要转向构建产物，而不是依赖目录。
三种变式共享同一条判据：凡是"没声明却能引入"的行为，都是借来的，随时要还。把这条判据交给团队，比记住任何具体案例都值钱。
团队治理清单：把根治落到制度
事故处置之外，把防幽灵依赖固化成四条团队规约，写进贡献指南。规约一：引入必声明。 代码评审的第一问——这个包在清单里吗；配合代码检查规则让未声明引入在本地就报错，不必等到流水线。规约二：补全要当次提交。 发现幽灵引入，修复提交与功能提交同批合入，不留"回头再补"的欠账。规约三：季度清查。 用依赖核对工具跑一遍全仓未声明引入扫描，作为季度技术卫生例行项，输出清单与处置记录。规约四：新成员第一课。 把 2.4 节的链路图放进新人入门材料——事故的最好预防是新人不再依赖编辑器补全的"好心"。
四条规约的成本都在分钟级，而它们拦下的是本节开头那种以周计的排障。工具会换代，"声明你所用"这条纪律不会——它值得成为团队肌肉记忆的一部分。
本节要点回顾
- 幽灵依赖四环链路：间接依赖入场、提升到顶层、编辑器补全引入、清单无记录——四环齐备才会成灾；
- 爆雷机理：上游更新改变顶层目录，幽灵包消失而"本地说谎"，CI 先死；
- 应急处置：把幽灵包正式声明进清单，一行命令止血；
- 根治三档：代码规则拦截、流水线清单核对、换严格隔离布局工具，按改动半径递增；
- 三种变式：等价替换膨胀产物、版本漂移行为异常、环境差异延迟爆雷，判据统一为"未声明的引入都是借来的"。
至此第二章两台引擎全部勘验完毕。第三章进入全册重心：解析出的方案如何被锁文件冻结成不可抵赖的快照——以及当两份快照在合并时撞车，该怎么勘验处置。