四、环境依赖问题：Node.js 版本、Python 包冲突、JDK 不匹配，排查与修复

环境依赖的坑，几乎每个 CI 流水线都会踩。说白了，就是你的代码跑在什么「土壤」上——Node.js 版本不对、Python 包冲突、JDK 不匹配，这三兄弟是 CI 集成测试失败的头号惯犯。我自己带团队那几年，至少有一半的流水线红线都是它们搞出来的。嗯，一个一个来拆。

4.1 Node.js 版本：你以为装对了，其实没装对

先讲 Node.js。很多项目 package.json 里写了 "engines": {"node": ">=14.0.0"}，但 CI 环境中装的可能是 12.x。为什么？因为 Docker 镜像的默认 Node 版本没更新，或者 .nvmrc 文件根本没被读。

我记得有一次，CI 跑的 Node 版本是 14，但本地开发用 18，结果 fs.promises.cp 在 14 里不支持，CI 直接报错。解决办法：统一 nvm 管理，CI 里先执行 nvm install 再 nvm use，或者用 docker run --env NODE_VERSION=18.12.0 显式指定。

4.2 Python 包冲突：requirements.txt 和 setup.py 打架了

Python 的环境问题，比 Node.js 更恶心。因为 pip 的依赖解析是「扁平化」的，两个包可能同时要求不同版本的同一依赖，结果只有一个版本被安装，另一个包就炸了。最常见的是 numpy、pandas、scikit-learn 这些科学计算包互相掐架。

我建议你在 CI 里加一行：

pip check

这个命令会列出所有有冲突的包。如果它返回非零，那恭喜你，找到原因了。然后再用 pipdeptree 看依赖树：

pip install pipdeptree
pipdeptree --warn silence | grep -E "^\s+-"

说一下我踩过的坑。有次项目用了 Django 3.2 和 celery 5.2，结果 celery 依赖的 kombu 版本太低，和 Django 的 async 关键字冲突。CI 里 pip install 成功，但一跑单元测试就报 SyntaxError。解决办法：锁定所有子依赖版本，用 pip freeze > requirements.txt 再检查，或者直接上 pip-tools 生成锁定文件。

4.3 JDK 不匹配：编译时好好的，运行时崩了

Java 项目的 CI 环境依赖，主要就是 JDK 版本。你本地用 JDK 11 编译，CI 里装的是 JDK 17，编译器可能过不了（比如 --release 11 要求 --add-exports 不同）。或者更隐蔽的：编译用 JDK 11，运行时用 JRE 8，结果字节码版本不对直接 UnsupportedClassVersionError。

我个人习惯在 pom.xml 或 build.gradle 里显式声明 java.version 或 sourceCompatibility，同时在 CI 脚本里用 java -version 打印：

mvn -version
java -version

另一个容易忽略的是：环境变量 JAVA_HOME。我曾经在一个 Jenkins 节点上发现 JAVA_HOME 指向 JDK 11，但 PATH 里的 java 是 JDK 8。结果 mvn compile 用的 JDK 11 编译，mvn test 却调了 JDK 8 的 JVM。解决办法：统一 JAVA_HOME 和 PATH，或者用 sdkman 管理。

4.4 通用排查方法论：三步走

1. 读日志 – 别闭眼。先看 CI 执行日志中依赖安装阶段的输出，比如 npm install 或 pip install 有没有 warning。
2. 复现 – 在另一台干净的机器或 Docker 容器里复现。拿 CI 的镜像跑一遍，本地重现问题。
3. 锁定版本 – 不管什么语言，锁定所有依赖（包括传递依赖）到一个固定版本。Node 用 lockfile，Python 用 requirements.txt + pip freeze，Java 用 gradle.lockfile 或 Maven 的 versions:lock-snapshots。