应优先使用 python:3.9-slim 多阶段构建而非 alpine，因 musl libc 导致预编译包缺失、需源码编译失败率高；builder 与 runner 阶段须严格分离，runner 中仅复制 site-packages 和代码，并用 --no-cache-dir 及显式清理 pycache 和 .pyc。
直接用 python:3.9-slim + 多阶段构建，能砍掉 60% 以上体积，部署拉取速度翻倍。Alpine 看似更小，但对多数 Python 项目是隐性成本陷阱。
为什么不能直接用 python:3.9-alpine？
Alpine 使用 musl libc，而绝大多数预编译的 Python 包（尤其是含 C 扩展的 numpy、psycopg2、pydantic）只提供 glibc 兼容的 wheel。结果就是 pip 强制从源码编译——耗时、失败率高、还可能漏装 gcc 或 musl-dev 导致报错 fatal error: Python.h: No such file or directory。
常见错误现象：
-
pip install psycopg2卡住或报编译错误 - 镜像构建时间比
slim版本长 2–3 倍 - 运行时报
ImportError: libpq.so.5: cannot open shared object file
多阶段构建必须拆开 builder 和 runner 镜像
builder 阶段要装编译工具，runner 阶段必须彻底剥离它们——否则体积没变，只是“看起来分开了”。关键不是写两个 FROM，而是确保最终镜像里连 gcc 的二进制文件都不存在。
立即学习“Python免费学习笔记（深入）”；
实操要点：
- builder 阶段用
python:3.9-slim（不是alpine），RUN 中合并安装和清理：apt-get install -y --no-install-recommends build-essential && apt-get clean && rm -rf /var/lib/apt/lists/* - runner 阶段必须用独立的
FROM python:3.9-slim，不能COPY --from=builder /usr/local整个目录——只复制/usr/local/lib/python3.9/site-packages和你的代码 - 避免在 runner 阶段再执行
RUN pip install，那会让所有依赖重新进一层
pip 安装必须加 --no-cache-dir 并清理 __pycache__
pip 默认会把下载的 wheel 缓存在 /root/.cache/pip，这个路径虽然不在 SITE-PACKAGES 下，但会固化进镜像层。不清理，光缓存就能占 100MB+。
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
正确写法（单条 RUN，保证原子性）：
RUN pip install --no-cache-dir -r requirements.txt \ && find /usr/local/lib/python3.9/site-packages -name "*.pyc" -delete \ && find /usr/local/lib/python3.9/site-packages -name "__pycache__" -delete
注意：--no-cache-dir 是 pip 参数，不是 docker build 参数；__pycache__ 清理必须显式执行，Python 运行时不会自动删。
.dockerignore 文件常被忽略但极其关键
Docker 构建时默认把整个上下文（当前目录）打包上传。如果项目根目录下有 venv/、node_modules/、logs/ 或大模型权重文件，它们虽未被 COPY，却已进入构建上下文——拖慢 docker build 启动，还可能意外触发缓存失效。
必须包含的排除项：
**/__pycache__-
venv/、.venv/ **/*.log.git/-
data/（除非你真要 COPY 数据）
漏掉 .git 会导致每次 git commit hash 变更都让第一层缓存失效——哪怕你只改了 README。
最易被忽略的一点：多阶段构建中，builder 阶段的 apt-get clean 和 rm -rf /var/lib/apt/lists/* 必须写在同一层 RUN 指令里。分开写，中间层残留的 lists 目录就永远删不掉了——Docker 分层机制决定了删除操作只能新增一层标记，无法擦除前层内容。
