本文摘要：Python 服务用全量镜像部署，体积 1.2GB，CI 构建超过 12 分钟。多阶段构建配合 slim 基底可将最终镜像压至 95MB，关键机制是只保留最后 FROM 阶段的层。
一、问题与结论
现场环境为 Docker 26 + compose v2。一个仅依赖flask和gunicorn的 Flask 服务，原始 Dockerfile 直接基于全量镜像：
FROM python:3.12 WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY app.py . EXPOSE 5000 CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]BuildKit 输出显示基础镜像约占 1.0GB，pip 包仅增加约 30MB：
=> [1/5] FROM docker.io/library/python:3.12 (1.0GB) => [4/5] RUN pip install ... (30MB)CI 全量构建（无缓存）约 12 分钟，拉取基础镜像占大头。改用多阶段构建后最终镜像可压至约 95MB——省下的是 builder 阶段的编译工具链和缓存（不进入最终镜像），丢掉的是调试工具和 C 扩展的运行时共享库（需在 runtime 阶段显式补装）。
二、排查与选择依据
python:3.12全量镜像基于 Debian，预装 gcc、g++、make、libc6-dev 等完整工具链。设计意图是"零障碍安装任何 pip 包"——包括需要源码编译 C 扩展的包。官方同时提供两个精简变体：
| 变体 | 含编译器 | 典型大小 |
|---|---|---|
python:3.12 | 是 | ~1GB+ |
python:3.12-slim | 否 | ~150MB |
python:3.12-alpine | 否 | ~50MB |
以上大小随镜像 tag 更新波动，以docker images实际显示为准。
多阶段构建要求 Docker 17.05+；Docker 23.0 起 BuildKit 默认启用，COPY --from缓存判断比旧 builder 更精确，但首次构建可能因拉取两个基础镜像而更慢。其机制：同一 Dockerfile 中多个FROM创建隔离文件系统，构建完成后只有最后一个阶段的层进入最终镜像——builder 阶段的编译器、apt 缓存、pip 缓存全部不打包。
由此推出一个常见误解的澄清：builder 阶段加不加pip install --no-cache-dir不影响最终镜像大小，它只影响 builder 阶段自身的层体积和构建缓存效率。
替代方案与取舍
| 方案 | 选择条件 | 代价 | 边界 |
|---|---|---|---|
| 多阶段 + slim 基底（本文） | 依赖可通过预编译 wheel 安装，或愿意在 builder 编译 | Dockerfile 复杂度增加 | C 扩展运行时库需显式补装 |
直接用python:3.12-slim | 所有依赖有预编译 wheel | 遇到需源码编译的包直接构建失败 | 无法处理任何需 C 编译的依赖 |
| 单阶段 slim + 同层安装/删除工具 | 依赖少、RUN 可合并 | 改依赖导致全层重跑，CI 更慢 | 安装和删除必须在同一个 RUN 中 |
| Alpine 直接安装 | 依赖有 musl 版本 wheel | musl 下 C 扩展性能可能降低 | 部分包在 musl 下编译困难 |
| distroless 运行镜像 | 只需运行时最小文件集 | 无法docker exec调试 | 需要团队有较强的可观测性基础 |
如果团队线上排查高度依赖docker exec进容器执行curl、wget等命令，slim 方案的排查成本会显著上升。此时直接用全量镜像、用存储成本换运维效率，反而是合理选择。
三、关键原理
C 扩展的编译期/运行时断层：mysqlclient、psycopg2等带 C 扩展的包，编译时需要-dev包（头文件 + 编译工具），运行时需要对应的共享库.so文件。builder 阶段装的是-dev包，COPY --from复制的 C 扩展.so能带过来，但它链接的系统共享库没有跟过来。runtime 阶段必须显式安装对应的运行时库包（不带-dev后缀）。
跨 libc 不兼容：builder 用 Debian（glibc）、runtime 用 Alpine（musl）时，C 扩展必然加载失败——两者的动态链接器路径和 C ABI 完全不同。纯 Python 包不受此限制。
venv 的符号链接依赖：python -m venv /opt/venv生成的环境内部 Python 指向/usr/local/bin/python的符号链接。两个阶段同版本官方镜像时路径一致，链接可正常解析；跨发行版复制时符号链接可能失效。
Python 3.12 移除 distutils（PEP 632）：部分旧包在pip install时仍尝试import distutils，在 3.12 下直接报错。遇到此类构建失败，先确认包版本兼容性，而非归因于多阶段构建。
四、可运行示例
项目结构：
project/ ├── Dockerfile ├── requirements.txt # flask==3.0.0, gunicorn==21.2.0 └── app.py # 返回 "Image slimmed successfully."多阶段 Dockerfile：
FROM python:3.12 AS builder WORKDIR /app RUN python -m venv /opt/venv COPY requirements.txt . RUN /opt/venv/bin/pip install --no-cache-dir -r requirements.txt FROM python:3.12-slim WORKDIR /app COPY --from=builder /opt/venv /opt/venv ENV PATH="/opt/venv/bin:$PATH" COPY app.py . EXPOSE 5000 CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]构建与验证：
dockerbuild-tslim-demo.dockerrun-d-p5000:5000 slim-democurlhttp://localhost:5000dockerimages slim-demo五、验证结果与边界
预期输出：curl返回Image slimmed successfully.；docker images显示镜像约 95MB。
实际输出：未在本机独立复现上述构建。1.2GB 与 95MB 数值来自作者环境观测，随镜像 tag 更新波动，以docker images实际显示为准。
常见失败：若requirements.txt中加入mysqlclient等带 C 扩展的包，runtime 阶段 import 时触发：
ImportError: libmariadb.so.3: cannot open shared object file: No such file or directory根因：builder 阶段安装了default-libmysqlclient-dev（提供头文件和编译工具，Debian 上实际解析为 MariaDB 客户端开发包），runtime 阶段缺少对应的运行时共享库。修复方式是在 runtime 阶段显式安装不含-dev后缀的运行时库包：
RUN apt-get update && apt-get install -y --no-install-recommends \ libmariadb3 \ && rm -rf /var/lib/apt/lists/*每补装一个运行时库包，镜像体积增加几 MB 到几十 MB——这就是"省了什么丢了什么"的核心张力。此外，slim 镜像中没有curl、wget，apt-get install需先执行apt-get update，线上排查网络问题时需提前规划替代手段。
参考资料
- Docker Hub 官方 Python 镜像文档
- Docker Multi-stage builds 文档
