核心判断是必须用多阶段构建：它通过分离编译环境（builder）与运行环境（runtime），解决镜像体积膨胀和编译工具链残留问题，尤其对含C扩展的包（如numpy、pytorch）至关重要。
Python项目打包成Docker镜像的核心判断
直接上结论：用多阶段构建（multi-stage build）不是为了“显得高级”，而是为了解决两个实际问题——镜像体积爆炸和运行时暴露编译依赖。如果你的 requirements.txt 里有 numpy、pytorch 或 cryptography 这类带 C 扩展的包，单阶段构建几乎必然导致最终镜像比实际需要大 2–3 倍，且包含 gcc、python-dev 等不该出现在生产环境的东西。
为什么 build stage 和 runtime stage 必须分离
Python 的很多包在安装时需要编译（比如 psycopg2-binary 是例外，但 psycopg2 不是），而编译完的 .so 文件只依赖 libc 和 Python 解释器，不依赖编译工具链。多阶段的本质就是：第一阶段装好所有依赖并完成编译，第二阶段只拷贝 site-packages 和代码，不带任何构建痕迹。
- build stage 用
python:3.11-slim-bookworm或python:3.11-bullseye（避免 Alpine 的 glibc 兼容性坑） - runtime stage 必须用同 base OS 的 slim 镜像（比如都用 bookworm），否则可能因 libc 版本不一致导致
ImportError: xxx.so: cannot open shared object file - 不要在 runtime stage 里
RUN pip install—— 这会让 pip 缓存和中间层残留，失去多阶段意义 -
COPY --from=builder要精确到目录，别用COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages这种粗暴路径，优先用COPY --from=builder /usr/local/lib/python3.11/site-packages/ /usr/local/lib/python3.11/site-packages/（末尾斜杠表示内容复制）
Dockerfile 多阶段写法的关键细节
一个典型但易错的结构如下，重点看注释掉的陷阱点：
FROM python:3.11-slim-bookworm AS builder
WORKDIR /app
COPY requirements.txt .
# ✅ 正确：先装基础依赖再装业务依赖，利用 layer 缓存
RUN apt-get update && apt-get install -y --no-install-recommends \
gcc libc6-dev && rm -rf /var/lib/apt/lists/*
RUN pip wheel --no-cache-dir --no-deps --wheel-dir /wheels -r requirements.txt
<p>FROM python:3.11-slim-bookworm
WORKDIR /app</p><h1>❌ 错误：COPY --from=builder /wheels 没用，wheel 是中间产物</h1><h1>✅ 正确：把 wheel 安装进干净 site-packages，再清理 pip cache</h1><p>COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir --find-links /wheels --no-index --upgrade . && \
rm -rf /root/.cache/pip /wheels
COPY . .
CMD ["gunicorn", "app:app"]
- 用
pip wheel而不是pip install在 builder 中，是为了确保 wheel 是可复现、可离线安装的；--no-deps防止重复安装依赖（由pip install --find-links统一处理） - runtime stage 的
pip install必须加--no-cache-dir，否则会在镜像里留下/root/.cache/pip（几百 MB） - 如果项目有
pyproject.toml且用了setuptools构建，builder 阶段要额外RUN pip install setuptools wheel
容易被忽略的兼容性雷区
不是所有 Python 包都能无痛跨阶段迁移。以下情况会直接失败：
立即学习“Python免费学习笔记（深入）”；
-
tensorflow或torch的 CPU 版本在 builder 中编译后，runtime 阶段必须用完全相同的 Python minor 版本（如 3.11.8 → 3.11.9 可能因 ABI 微变报undefined symbol） - 用
uv替代pip加速构建时，uv pip wheel生成的 wheel 默认含平台标记（如cp311-cp311-manylinux_2_31_x86_64.whl），但若 builder 是 x86_64、runtime 是 ARM64，就会安装失败 —— 此时需显式加--python-version 3.11和--platform manylinux2014_x86_64 -
pydanticv2 之后的某些版本，在 slim 镜像中缺少tzdata会导致datetime解析异常，需在 runtime stage 补RUN apt-get update && apt-get install -y tzdata
最稳妥的做法：build 和 runtime 都固定完整镜像 tag（如 python:3.11.8-slim-bookworm），而不是用 python:3.11-slim-bookworm 这种浮动 tag。
