多阶段构建可显著减小镜像体积,因单阶段会残留编译工具、缓存、测试依赖及源码等运行时无需内容;builder阶段生成产物,runtime阶段仅保留最小运行环境,通过COPY --from精准传递依赖目录,并清理__pycache__等冗余文件。

直接用多阶段构建,否则镜像里一定会混进编译工具、缓存、测试依赖这些运行时完全不需要的东西。
为什么单阶段 Dockerfile 一定臃肿
单阶段构建把所有东西塞进一个镜像:Python SDK、pip 缓存、requirements.txt 中的 dev-dependencies(比如 pytest、mypy)、甚至源码本身。哪怕你用 python:3.10-slim,只要在同一个 RUN 里装依赖又删缓存,Docker 层机制仍会保留那些“已删除但未真正消失”的文件数据。
-
apt-get clean或rm -rf /var/lib/apt/lists/*不会减小镜像体积,只是在当前层新增“删除操作”,上层依然存在原始文件 -
pip install --no-cache-dir能避免 pip 自身缓存,但无法清除build/、__pycache__/、.git等目录——它们只要被COPY . .进去就永远在 - 如果你的
requirements.txt包含-e .或本地路径包,pip install会把整个项目源码以 develop 模式链接进去,最终镜像里全是 .py 文件
多阶段构建必须分清两个阶段职责
第一阶段叫 builder,只负责“生成可部署产物”;第二阶段叫 runtime,只负责“运行这个产物”。两者基础镜像可以完全不同。
- 构建阶段用
python:3.10或python:3.10-slim:它带完整 pip、setuptools、wheel 工具链,能处理pyproject.toml、C 扩展编译等复杂场景 - 运行阶段必须用
python:3.10-slim或更轻的python:3.10-alpine:不带编译器、不带头文件、不带包管理器缓存,只留解释器和标准库 - 两个阶段之间只传
venv目录或site-packages打包后的 tar.gz,而不是整个项目目录;或者更干净的做法:只复制pip install --target指定的纯 Python 依赖目录
COPY --from=builder 的实际写法和常见错误
很多人以为 COPY --from=builder 是“复制文件”,其实它是“复制某一层文件系统里的路径内容”,而路径是否真实存在、权限是否可读,全看构建阶段最后那个 RUN 是否真的生成了它。
立即学习“Python免费学习笔记(深入)”;
- 错误写法:
COPY --from=builder /app/venv .—— 如果构建阶段没执行python -m venv venv && pip install --target venv/lib/python3.10/site-packages -r requirements.txt,这个路径根本不存在 - 推荐写法:构建阶段用
pip install --target /install -r requirements.txt,然后运行阶段COPY --from=builder /install /usr/local/lib/python3.10/site-packages,再COPY . .放应用代码,这样依赖和代码彻底分离 - 别忘了在运行阶段加
ENV PYTHONPATH=/usr/local/lib/python3.10/site-packages,否则 Python 找不到你手动复制进来的包 - 如果项目有 C 扩展(如
numpy、psycopg2),alpine 镜像可能缺 musl-dev,得换回slim;或者干脆在构建阶段编译好 wheel,运行阶段只pip install那个 wheel 文件
容易被忽略的体积黑洞:.pyc 和 __pycache__
即使你用了多阶段,如果在构建阶段执行了 python -m compileall 或任何触发字节码生成的操作,__pycache__/ 会被一并 COPY 进去。而 Python 运行时会在首次导入时自动生成 .pyc,这些预生成的缓存毫无意义,还占几 MB 到几十 MB。
- 构建阶段结尾加一句
RUN find /app -name '__pycache__' -type d -exec rm -rf {} + 2>/dev/null || true - 或者更彻底:在
COPY . .之后、RUN pip install之前,先清理掉源码里的缓存目录,避免它们进入构建上下文 - 注意
Dockerfile里的.dockerignore文件必须包含__pycache__、.git、tests/、docs/等非运行必需目录,否则它们会随上下文一起传给 Docker daemon,哪怕后续没 COPY 也会浪费构建时间


















