多阶段构建可使python生产镜像仅保留python3和main.py，避免单阶段中pip缓存、dev依赖、__pycache__等冗余内容；需分清build（全量工具）与runtime（最小运行集）职责，并注意c扩展兼容性及路径硬编码问题。
因为单阶段构建会把 pip 缓存、.pyc 文件、dev 依赖甚至编译器全塞进生产镜像，而多阶段构建能让你只保留 python3 和你的 main.py —— 其他全是噪音。
Python项目单阶段构建的典型膨胀点
很多 Python 镜像从 FROM python:3.11-slim 开始，看似精简，但只要执行了 RUN pip install -r requirements.txt，就埋下三个隐患：
-
pip默认缓存下载包到/root/.cache/pip，该目录不会被自动清理，每层都固化； -
requirements.txt里混着pytest、mypy、black等 dev-only 包，它们在生产中既不 import 也不执行； -
RUN python -m compileall或框架自动生成的__pycache__目录，会被完整复制进最终镜像，徒增几 MB。
如何用多阶段构建分离 build 与 runtime
关键不是“多写几个 FROM”，而是明确每个阶段的职责：build 阶段装全量工具链，runtime 阶段只放运行时最小集。
- build 阶段用
FROM python:3.11（含pip、gcc、setuptools），执行pip install --no-cache-dir -r requirements.txt和COPY . /app； - runtime 阶段切到
FROM python:3.11-slim或FROM gcr.io/distroless/python3，再用COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages复制已安装的包； - 务必在 build 阶段末尾加
RUN find /usr/local -name __pycache__ -delete 2>/dev/null || true，否则COPY --from会连缓存一起搬过去。
容易忽略的兼容性陷阱
Python 的多阶段构建不像 Go 那样天然二进制隔离，稍不注意就会在 runtime 阶段报错：
- 如果
requirements.txt含 C 扩展（如psycopg2-binary、cryptography），不能直接跨基础镜像复制site-packages——slim镜像缺libc符号或 OpenSSL 版本不匹配会导致ImportError； - 此时必须让 build 和 runtime 使用相同 libc 衍生版本（例如都用
debian:bookworm-slim作为底层），或改用pip install --only-binary=all强制二进制分发； -
COPY --from=builder /app /app看似安全，但如果app/下有硬编码路径的配置文件（比如写了/home/user/.cache），运行时仍可能因用户/目录缺失而失败。
真正省下的不只是几十 MB 镜像体积，是每次 docker pull 的网络耗时、K8s Pod 启动延迟，以及——当某天你发现线上镜像里居然有 vim 和 curl 时，那种后知后觉的寒意。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
