Docker构建时pip3 install -r与多条单独pip安装效果差异原因

问题本质是踩了Docker层逻辑、pip依赖解析规则两个机制的坑：

• 依赖解析作用范围差异是核心诱因
  执行pip3 install -r requirements.txt单条命令安装所有依赖时，pip会先读取全部包的版本约束（包括手动固定版本、未指定版本取最新的包），做全局依赖冲突校验，自动为所有未锁版本的包、以及所有包的传递依赖选择兼容版本安装。比如requirements中固定了django==3.1.2，pip就会自动选择适配该Django版本的django-debug-toolbar、django-colorfield等未锁版本包的历史兼容版，不会随意替换已固定版本的包，最终得到的整套依赖版本兼容、文件完整。
  拆成多条独立RUN pip3 install xxx执行时，每一条命令对应完全独立的pip解析进程：pip每次仅保证当前指定的安装包可用，不会校验之前Docker层中已安装的其他包的完整性。给出的requirements中有6个包未锁版本，这类包安装时默认拉取最新版，而最新版往往已经不兼容固定的Django3.1等老版本依赖，此时pip会直接将之前层中装好的固定版本包卸载、替换为符合当前单包要求的新版本，甚至删除部分传递依赖文件，整个过程不会抛出错误——毕竟对单次pip命令而言，仅需要完成当前指定包的安装任务，不需要对其他已安装包的可用性负责。最终构建出的环境依赖版本混乱，部分模块文件被删除或替换，启动Django时自然会提示找不到依赖。

• Docker镜像层的文件叠加逻辑会放大上述问题
  Docker每一条RUN指令都会生成独立的只读层，后续层的文件修改是基于上层的增量叠加。部分Python包安装时会修改easy-install.pth这类路径配置文件、或者更新包管理工具的软链接，若在不同RUN层分别装包，后续层安装时对这类全局配置文件的修改会直接覆盖之前层的记录，导致之前装好的包没有被加入Python的导入搜索路径，表现和未安装一致。

额外说明：拆成多条RUN提升构建速度的思路本身存在误区。Docker层缓存规则为「某层指令变动，该层之后所有层的缓存全部失效」，将依赖拆分为十几条RUN后，只要修改一个包的版本，后续所有安装层的缓存都会作废，构建速度反而比单条安装更慢。正确的提速方式是保留「先拷贝requirements.txt、再单条执行pip安装」的结构，配合BuildKit的pip缓存挂载功能，构建效率会比拆RUN高很多。

内容的提问来源于stack exchange，提问作者Romain Jouin