📚 课程目录第3章环境依赖问题

环境依赖问题：版本冲突导致崩溃

你遇到过这种情况吗？CI 环境一切正常，结果今天跑构建就崩了。看日志，全是莫名其妙的导入错误、API 不存在、或者类找不到。我刚入行时，花了整整两天才找出原因——两个不同的库依赖了同一个软件包的不同版本。说白了，这就是环境依赖的版本冲突。它就像传染病，一感染整个项目就瘫痪。

版本冲突的典型表现

我记忆里最惨的一次，是前端构建突然报 Module not found，但代码根本没有改动。查了 4 个小时，才发现最新的 CI 镜像里 lodash 被自动升级了，而另一个库要求 lodash@3.x。CI 环境每次拉镜像都不一样，这次就撞上了。

常见的症状有几种：

导入错误：某个包里的函数、类突然找不到。
类型不匹配：argument type mismatch 或 cannot convert。
运行时异常：比如 NoSuchMethodError、AttributeError。
构建终止：依赖解析失败，直接退出。

嗯，这些问题往往在本地复现不了，因为本地环境锁定了版本，而 CI 里依赖是动态解析的。

依赖解析的根源——从 YAML 到冲突链

为什么 CI 里容易触发版本冲突？简单说，依赖的依赖出了问题。你声明了 A 和 B，但 A 内部依赖 C 1.0，B 内部依赖 C 2.0。解析器一般会选择最新的兼容版本，但如果两个库对 C 的接口要求不兼容，冲突就冒出来了。

我做过一个实验：把 Python 项目的 requirements.txt 不加版本号，每次 pip install 都会拉最新版。结果第三天 CI 就挂了，原因是 pandas 升级后改了内部 API。你想想看，这不是自找麻烦吗？

核心原则：CI 环境里，依赖解析必须是确定性的——同样的代码、同样的环境配置，每次必须得到完全相同的依赖树。

实操：排查与修复版本冲突

遇到 CI 崩溃时，我建议按照下面的流程走。

1. 锁定错误日志中的关键行

大多数包管理器都会输出冲突的依赖链。比如 Python 的 pip 会告诉你：

ERROR: Cannot install requirements because these package versions have conflicting dependencies.
  The conflict is caused by:
    package-a 1.0 depends on requests>=2.0
    package-b 2.0 depends on requests>=3.0,<4.0

看到这种信息，你就知道凶手是谁了。

2. 导出依赖树，看清全貌

不同的语言对应的命令：

语言/工具	依赖树命令
Python (pip)	`pipdeptree`
Node.js (npm)	`npm ls`
Java (Maven)	`mvn dependency:tree`
Go (modules)	`go mod graph`

我个人习惯在 CI 脚本的第一个构建步骤里就加一条 npm ls --depth=5 2>&1 | head -50，这样失败时能立刻拿到依赖树日志。

3. 确定冲突点，强制锁定版本

一般有两种解法：

升级/降级冲突链中的某个库：比如把 package-a 升级到新版本，使其兼容 requests>=3.0。
在 dependencies 中直接声明中间库的版本：比如显式写上 requests==3.0.0，强制覆盖。

小提示：在 package.json 或 Gemfile 里添加 resolutions / override 字段，可以统一管理深层依赖的版本。比如 npm 的 overrides。

4. 写一个能复现崩溃的最小 Dockerfile

我曾经在本地死活复现不了，后来写了一个 Dockerfile，把 CI 镜像的 base 层固定下来，再逐步安装依赖，才发现了问题。这里的关键是锁定基础镜像的版本。你想想看，CI 镜像每天拉 latest，跟开盲盒有什么区别？

FROM node:16.14.0-alpine   # 别用 node:16-latest
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "test"]

预防策略：把「不确定」变成「确定」

版本冲突最好的治疗是预防。我把常用的方法列出来：

使用锁文件：package-lock.json、poetry.lock、Gemfile.lock，必须提交到版本库。
避免宽松版本声明：别写 "^1.0.0" 或 >=2.0，尽量锁定主版本号和次版本号。
定期更新依赖并走自动化测试：我每月会开一个 dependabot 的 PR，手动确认后再合并。
CI 环境预构建依赖层：把锁文件提前安装好，缓存起来，避免每次都重新解析。

注意：即使使用了锁文件，也要检查 CI 的镜像源是否一致。我遇过好几次，CI 里用了不同的 npm registry，导致锁文件里哈希校验失败，直接崩了。每次构建前最好先跑一次 npm ci 确保锁文件有效。

一张图看懂版本冲突的链式反应

下面这张图概括了依赖冲突从引入到崩溃的典型路径，以及对应的解决节点。建议你打印出来贴在工位旁边。

这张图从左到右反映了典型的冲突蔓延路径。我个人习惯在项目根目录放一个 .nvmrc 和 .node-version，锁定 CI 宿主环境。你还可加上一个 CI 前步骤——校验锁文件是否与 package.json 一致：

# .ci/check-lock.sh
if ! cmp -s package-lock.json <(npm install --package-lock-only 2>/dev/null); then
  echo "ERROR: package-lock.json is out of sync!"
  exit 1
fi

这东西救过我的命。那次同事手改 package.json 没更新锁文件，CI 直接丢出哈希不匹配。加上这个脚本后，推到远程时就被拦截了。

避坑指南：我曾经在 monorepo 里踩过更深的坑——两个子包的 lock 文件互相覆盖。后来用了 --frozen-lockfile 才治住。你也最好在 CI 脚本里加上 npm ci --frozen-lockfile 或 yarn install --frozen-lockfile，让构建在锁文件不一致时直接失败，而不是静默更新。

总结一下关键点

版本冲突的本质是传递依赖的不兼容。
锁文件是 CI 环境依赖确定性的第一道防线。
遇到崩溃先看依赖树，再定位冲突库，最后用 override 或升级解决。
CI 镜像版本要固定，不要用 latest 标签。

其实解决版本冲突并不难，难的是你愿意在项目初期就花时间搭好这套机制。省的那点功夫，后期崩溃一次全赔进去了。