Python Docker镜像体积过大主因是默认使用含冗余组件的Debian系基础镜像（如python:3.11达900MB），且未区分构建与运行阶段；通过多阶段构建（builder用slim、runtime用alpine）、精准COPY依赖、清理__pycache__/pyc/测试模块及禁用pip缓存，可将镜像从512MB降至约85MB。

为什么单阶段构建的 Python 镜像动辄 900MB+

因为 python:3.12 这类官方镜像默认带完整 apt 工具链、编译器、文档、测试套件，而你的 Flask/FastAPI 应用只用到 python 解释器和几个依赖包。拉取 1.2GB 镜像 → 冷启动耗时 8 分钟（10Mbps 网络）→ Auto Scaling 扩容卡住，这不是理论风险，是真实发生的线上故障。

多阶段构建必须写的两个 FROM 和 --from=builder

核心就两段：第一段用大镜像装依赖，第二段用小镜像只跑代码。关键不是“用了多阶段”，而是能否精准复制产物。

• FROM python:3.12-slim AS builder：只在构建阶段用，装 pip 包
• COPY --from=builder /build/site-packages ./site-packages：不复制源码、不复制 pip 命令本身，只复制安装好的包目录
• 漏掉 AS builder 或写错 --from=builder 名字，第二阶段就报 failed to compute cache key: failed to walk /var/lib/docker/tmp/buildkit-mount...

requirements.txt 必须先 COPY，且路径不能错

顺序错了，缓存就废了；路径错了，pip install -r requirements.txt 直接报 ERROR: Could not open requirements file。

提示词大师-python版

图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍

下载

• 必须 COPY requirements.txt .（注意结尾的 .），不是 COPY ./requirements.txt . 也不是 COPY requirements.txt /app/
• 如果 requirements.txt 在 ./src/ 下，就得写 COPY src/requirements.txt .
• 本地测试没问题，CI 流水线失败？大概率是 CI 的构建上下文没把 requirements.txt 带进去——检查 .dockerignore 是否误删了它

slim vs alpine：别为省 10MB 换一堆 C 扩展兼容性问题

用 python:3.12-slim-bookworm 是当前最稳选择；alpine 看似更小（~50MB），但 musl libc 导致 psycopg2、numpy、grpcio 安装失败或运行时报 Illegal instruction。

立即学习“Python免费学习笔记（深入）”；

• 确认你项目里有没有含 C 扩展的包：pip show psycopg2 numpy pandas grpcio
• 若存在，直接放弃 alpine，改用 python:3.12-slim-bookworm（约 120MB，兼容性好，Debian 生态）
• 想再压体积？等构建完用 docker run --rm -v $(pwd):/out your-image tar -C / -cf /out/rootfs.tar . 手动分析哪层占空间最大——90% 是 /usr/lib/python3.12/ 下的测试模块和文档，多阶段已帮你砍掉大部分

多阶段构建真正难的不是语法，是判断哪些东西“运行时真不需要”。比如 pylint、mypy、tests/ 目录，它们不该进最终镜像——哪怕只多 3MB，也会在每次扩容时被重复拉取、解压、校验。