依赖管理：四十一个直接依赖与四个升级窗口

依赖不会一次压垮你，它在你每次点升级时收一次利息。

一、拖了两年的那次升级

2026 年 5 月，陆远收到一条安全告警：一个鉴权相关的库有已知漏洞，当前版本在受影响范围内。这个依赖从 2024 年的原型项目沿用过来，到他打开 package.json 时，已经两年没升过。

他花了一个周六：9 小时，碰上 3 处破坏性变更，其中一处改了初始化参数的名字，另一处删掉了他一直在用的中间件钩子。升级完他补了 40 分钟的手动回归，才敢发布。

以下情境为教学假设，人物、引语和数字不代表经核实的真实案例。

这两年他并不是没看见升级提示。每个月都有十来个 PR，patch 的、minor 的、偶尔一个 major 的；他看一眼标题，觉得「应该没事」，就关掉了。积压不是一次决定，是三十次「下次再说」。

真正贵的不是那 9 小时，而是这两年里他一直在用带已知漏洞的版本，而且自己知道。

事后他回看了这两年的升级记录：每月大约 14 个 PR，两年就是 336 个。他合掉的不到一半，剩下的都在等一个「有空的时候」。等来的是一次必须在周末做完的升级。

一个人做依赖管理最容易犯的错，是把「没出事」当成「没问题」。没有出事只说明还没被扫到，不说明版本是安全的。

升级不是「有空再做」的任务，它和发布、备份一样，需要一个固定的槽位。槽位不在日历上，就一定被功能需求占掉，因为功能需求永远更急。

升级的成本不取决于版本跨度，取决于你隔了多久没做。

每月十四个升级 PR 不能一视同仁，分级之后大部分可以批量处理。

锁文件是发布物的一部分，不是开发机上的临时文件。

二、四十一个直接依赖和它们背后的三百一十八个包

41 个直接依赖是你能叫出名字的那一层，318 个传递依赖是它们带进来的。你能直接决定升级节奏的只有前 41 个，但出安全问题的往往是后 318 个，这就是必须把锁文件当发布物管的原因。

6 个近 12 个月无更新的直接依赖，处理原则是「记下来，不马上换」。它们没有更新可能意味着稳定，也可能意味着停更；区别要看仓库最近一次提交和 issue 响应，而不是看版本号。换掉一个依赖的平均成本远高于升级它。

传递依赖不能逐个看。318 个包每月产生的变更通知足够淹没你，可行做法是只在两种情况下处理：安全告警命中，或者某个直接依赖的 major 升级把它一起带上来。

这 41 个直接依赖里，真正承担业务语义的不到十个：框架、数据库访问、鉴权、支付、邮件。剩下的多是格式化、日期、日志这类工具库，它们出问题的概率低，替换成本也低。

把依赖按「业务语义」和「工具」分开，升级策略就自然分开了：业务依赖的 major 要读迁移指南，工具库的 major 往往改个 import 就好。这一层分类不需要工具，一张两列的表就够。

还有一类不能忘：只在构建时用到的依赖。它们不进生产镜像，出问题只影响构建，可以放在 patch 批量里一起处理，不必占用窗口的注意力。

三、把每月十四个 PR 分三级

逐个看的成本是 14 × 10 = 140 分钟/月，一年 28 小时。分级之后是 5 + 24 + 15 = 44 分钟/月，一年 8.8 小时，差 19.2 小时。

分级的依据不是版本号好看，而是失败模式不同。patch 挂掉通常是构建或测试直接报错，批量跑一次就能发现；minor 挂掉可能是行为变化，需要读变更说明；major 挂掉往往是编译不过或语义变了，必须单独发布并留回滚记录。

四个升级窗口安排在每季度第一个发布日，每个 45 分钟，一年 3 小时。窗口的作用不是「那天必须升完」，而是给升级一个固定的、不会被功能需求挤掉的位置。

窗口里做的事有固定顺序：先合 patch 批量，再逐个看 minor，最后判断 major 是这次做还是排到下个窗口。顺序反过来会浪费时间——major 卡住的时候，patch 其实早就该合了。

窗口允许「跳过」。某次 major 的迁移指南明显超出 45 分钟，就记下来排到独立的发布，而不是硬做完导致发布延迟。跳过的要写原因和复查日期，否则它就变成了新的积压。

四、复算：三百五十九个包与十九点二小时

包总量        41 + 318 = 359
年度窗口      4 × 45 = 180 分钟 = 3 小时
逐个处理      14 × 10 = 140 分钟/月
逐个年成本    140 × 12 = 1,680 分钟 = 28 小时
分级批量      patch 5 + minor 24 + major 15 = 44 分钟/月
分级年成本    44 × 12 = 528 分钟 = 8.8 小时
每年节省      28 − 8.8 = 19.2 小时
积压对比      9 − 3 = 6 小时（一次补升级 vs 全年窗口）

28 小时对 8.8 小时，差的是「每个 PR 都从头理解一遍」和「同一类 PR 一次处理完」的区别。19.2 小时接近半周的工程时间，而它换来的不是更快的升级，是同样的覆盖率。

积压的账更直接：一次补两年是 9 小时，分摊到每年是 4.5 小时，比每年 3 小时的窗口还贵，而且这 9 小时是不可选的——告警来了就得做，通常还赶在周末。

反过来看，3 小时窗口对 9 小时积压，差 6 小时；如果算上积压期用着有已知漏洞的版本，这个差额还会扩大，只是漏洞被利用的概率没法用四则运算估。

比时长更麻烦的是形状：45 分钟可以从一个工作日的缝隙里挤出来，9 小时不行。积压的代价有一半不在小时数，而在它必须占用一整块不被打断的时间。

19.2 小时是分级带来的直接节省，没有算上「不用每次重新建立上下文」的隐性收益。14 个 PR 逐个看，每次都要重新判断这个库是干什么的；批量处理只需要判断一次。

这些数字的意义不在精确，而在比例：窗口是小时级，积压是整天级，告警后的应急是周末级。把升级放在哪一档，决定的是它会不会侵入你的休息时间。

五、行动清单与复算验收

• 把 41 个直接依赖列成一张表，标出每个的用途与当前版本。
• 给 6 个近 12 个月无更新的依赖标注「替换观察」，写上下次复查日期。
• 在日历上固定四个升级窗口，每季度第一个发布日，各 45 分钟。
• 把每月 14 个 PR 按 patch、minor、major 三级打标签，patch 只批量处理。
• major 升级单独占一个发布，发布说明里附回滚方式。
• 锁文件提交进仓库，CI 用不可变安装，生产镜像按锁文件构建。
• 打开依赖告警，只对直接依赖和告警命中的传递依赖设通知。
• 每次窗口结束记录：合并了几个、跳过了几个、跳过的原因。

验收标准：任意连续 12 个月内，四个升级窗口全部执行，且没有超过 2 个大版本的积压；每次 major 升级都能在发布记录里找到对应的回滚方式。

依赖管理的目标不是「永远最新」，而是「想升的时候升得动」。窗口、分级、锁文件这三件事，都是为了保住这个能力。

如果只能先做一件事，把四个窗口写进日历。它不需要改任何代码，却决定了剩下七条有没有执行的机会。

清单的前四条是「这个月就要做完」的，后四条是「这个季度内」的；和上一篇的迁移清单一样，拆成两批比排一个完整计划更容易真的开始。

使用边界与实操验收

这套节奏不适用于安全事件。 告警命中且确认可利用时，不等窗口，直接按事件响应走：先评估暴露面，再决定是升级、禁用功能还是加临时缓解。

它不解决「该不该用这个依赖」。 升级管的是版本，选型管的是要不要它；6 个停更依赖的处理属于后者，需要回到选型判据，而不是靠升级窗口解决。

与维护账本专题的分工。 账本按产品盘点证书、运行时与政策；本篇按包与窗口排队。同一个依赖在两边都出现时，以账本的到期日为准，窗口只负责执行。

什么时候该停下来。 当一个 major 升级需要改动超过三个模块，或需要改数据库结构时，它已经不是升级，而是一次迁移；拆成独立项目，按迁移的三步纪律走。

运维侧的验收动作。 在干净环境用锁文件做一次不可变安装，比对产物哈希与上一次发布是否一致；再挑一个 minor 升级走完整流程，记录从开 PR 到合并的实际耗时。

关键参考与核验范围

核验日期：2026-10-26。以下文档用于核对概念与规则，本文所有数字均取自全组教学基线，不取自这些文档。

• About semantic versioning ：用于核对主、次、补丁三个号段各自承诺什么。
• npm ci ：用于核对不可变安装与普通安装的行为差异。
• Packages ：用于核对包入口、导出与依赖解析规则。
• About Dependabot alerts ：用于核对告警的触发条件与可见范围。

四份文档覆盖的是一条链：版本号承诺什么、安装是否可复现、包怎么解析、告警怎么触发。链上任何一环没配好，窗口里做的事都会打折扣。

引用口径。 上述文档只用于确认版本号语义、安装行为与告警机制；41、318、359 与所有耗时均来自本文的教学基线，不来自这些文档。

核验范围。 上述四个入口在 2026-10-26 实测可公开访问（HTTP 200）；未核验各项目的最新版本、价格与配额。

如何自行复核。 数一遍自己项目的直接依赖数量，再看最近一个月收到的升级 PR 有多少条；把本文的 41 与 14 换成你的数字，分级前后的差额按同样比例缩放即可。

系列导航

• 上一篇：数据模型与迁移：三十四张表与一次只能动一处的改动
• 下一篇：技术债预算：十八条债、二十四分钟与 7.5% 的工程时间
• 回到目录：一个人的架构：技术选型、模块边界与演进
• 相关阅读：维护负债账本：依赖、证书与平台政策的季度巡检 、跨平台构建矩阵：三系统两架构的 CI 成本 、可替换性：七个外部服务与一层适配