多阶段构建python项目应剔除venv杂质，仅复制运行所需文件：builder阶段用--target安装依赖到干净目录，runner阶段仅copy site-packages并禁用pip操作。
多阶段构建在 python 项目中剔除虚拟环境杂质，核心是不让 venv 本身进入最终镜像，而是只提取其中真正运行所需的文件——解释器、已编译的包、字节码（可选），同时彻底排除 pip、setuptools、.pyc 缓存、测试模块、文档和临时构建产物。
用 builder 阶段创建 venv，但不复制整个目录
不要 COPY 整个 /opt/venv 或 /root/.local 目录。这些目录里混着大量非运行必需内容：
-
/bin/pip、/bin/python等可执行脚本只是符号链接或包装器，实际运行靠的是底层系统 Python -
/lib/python3.x/site-packages/下可能包含tests/、docs/、.dist-info/以外的冗余文件 -
/lib/python3.x/里默认带的ensurepip、idlelib、tkinter等模块，绝大多数 Web 或 CLI 服务根本用不到
只复制 site-packages 中真正需要的依赖
推荐在 builder 阶段使用 --target 安装到干净目录，而非激活 venv 后 pip install：
RUN pip install --no-cache-dir --target /app/deps -r requirements.txt- 这样所有第三方包都集中放在
/app/deps，不含 venv 的 bin、pycache、.dist-info 冗余结构 - runner 阶段只需
COPY --from=builder /app/deps /usr/local/lib/python3.11/site-packages/ - 如果项目用了
--user安装，则复制/root/.local/lib/python3.11/site-packages/，并设ENV PYTHONPATH=/root/.local/lib/python3.11/site-packages
清理 C 扩展残留与编译中间产物
含 C 扩展的包（如 psycopg2、cryptography）容易在 builder 阶段留下体积大户：
- 安装后立即清理：
RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/pip-build-* - 避免使用 Alpine：musl libc 导致 wheel 不兼容，被迫源码编译，生成大量
.o、.so和临时文件 - 优先选用
python:3.11-slim，它支持绝大多数预编译 wheel，跳过本地编译环节
runner 阶段禁用任何 pip 操作
哪怕只写一行 RUN pip install --no-cache-dir xxx，也会把 pip 自身、wheel 缓存、解压临时目录全固化进镜像层：
- runner 镜像里不装
build-essential、不配gcc、不放requirements.txt - 所有依赖必须由 builder 阶段准备好，并通过
COPY --from=显式复制 - 业务代码用
COPY . .即可，无需再RUN pip install -e .或类似操作
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
