依赖升级恐惧症：采集项目怎么安全地升级第三方库

有个采集项目因为「一升级就出事」把所有依赖锁死了三年。直到 Python 版本和 requests 的安全通告都压到头上，才不得不做一次憋了半年的大升级——结果崩了三天，改了一堆「三年前的代码和新库不兼容」的接口。教训很贵：锁死不升级是「把升级债存进银行」，利息是灾难。 这篇记录后来建立的依赖升级机制。

第一步：盘点现状

升级机制之前先回答三个问题：

1. requirements.txt 里是锁死的精确版本（requests==2.32.3），还是 >= 这种宽松写法？
2. 有没有 lockfile（pip-tools 的 requirements.lock 或 uv.lock）？——锁死但可重现
3. 有没有自动化的「过期依赖检查」？

最常见的病是两种极端：全宽松（requests>=2.0，某天静默升级行为变了，没人知道）和全锁死（三年不升）。两个都要治。

第二步：建立升级节奏

小版本（patch/minor）：每周一次，自动化

pip list --outdated            # 看有哪些可升级
pip install --upgrade requests # 升级
pytest                         # 跑测试

小版本升级风险低，每周花十分钟，债务永不积累。

大版本（major）：按需 + 专项

• 先读 changelog 的 breaking changes 列表
• 对照代码逐条找「受影响的位置」
• 在 staging 环境验证，再灰度上线

安全通告：立即

有安全通告的依赖优先级最高，不等节奏，单独处理。

第三步：安全网（升级不慌的前提）

升级敢频繁，靠的是「升级错了能立刻知道」：

1. fixture 测试。 用真实响应做测试样本——库行为变了、解析逻辑变了，测试会挂，而不是上线后才炸（测试篇的做法，升级时是核心防线）。

2. 冒烟脚本。 用真实 Key 跑一遍关键路径（采集 → 落库 → 报表各一次），确认端到端没坏。

3. 影子对比。 升级前后跑同一批输入，diff 输出：

# 升级前跑一遍，存基线
# 升级后跑一遍，对比
assert new_output == baseline

这三个网搭好，升级就从「赌一把」变成「验证一下」。

第四步：大版本迁移的流程

以 Python 大版本或 requests 大版本为例，流程固定五步：

1. 列出 changelog 的 breaking changes，逐条对应到自己的代码
2. 改代码 + 更新 fixture（如果行为变化是预期的）
3. 全部测试跑绿
4. staging 跑一个完整日周期（采集 → 报表）
5. 灰度发布，观察 24 小时

别憋大升级——小步升级到位的项目，几乎不需要这种「大迁移」。

踩坑记录

坑 1：全宽松写法。 requests>=2.0 让依赖在某天静默升级，行为变了只有线上发现。锁精确版本 + lockfile。

坑 2：全锁死。 三年不升级 = 安全漏洞 + 一次大爆炸。固定节奏小步升。

坑 3：升级不跑测试。 没有 fixture 测试的项目，升级全凭运气。先搭安全网，再谈升级。

坑 4：大版本憋一次。 债务越多，迁移越大，风险越大。小版本高频还债，大版本就永远不大。

坑 5：忽略传递依赖。 升级 A 库，B 库的兼容性崩了。pip check（或 pipdeptree）检查依赖一致性。

坑 6：升级后不回看行为变化。 新版本的行为差异被当成「bug」，白查半天。升级时读 changelog 是流程的一部分，不是可选项。

工程清单

1. 锁精确版本 + lockfile，可重现
2. 小版本每周升级（pip list --outdated 驱动）
3. 大版本专项迁移：changelog → 改码 → 测试 → staging → 灰度
4. 安全通告立即处理
5. 安全网：fixture 测试 + 冒烟脚本 + 影子对比
6. pip check 检查传递依赖一致性

依赖升级的本质，是把「一次三年份的大迁移」拆成「每周十分钟的小动作」。升级频率和事故率往往是反比的——升得勤、升得小、每次验证，系统反而最稳定。采集项目尤其值得这么管：接口字段、库行为、解析逻辑任何一个静默变化，都是信誉事故。

接口响应结构变化时 fixture 会第一个告诉你，字段语义见 SerpBase 官方文档。你们的依赖是锁死还是放养？评论区聊聊升级事故。