多阶段构建是唯一能干净打包含c扩展python应用的方式，build和runtime阶段均用同源debian slim镜像，builder编译wheel并复制所需.so，runtime离线安装且精准copy，确保镜像轻量安全。
直接用多阶段构建，把编译和运行彻底分开——这是唯一能干净打包含 C 扩展（如 PyTorch、NumPy、cryptography、psycopg2）或自定义动态库的 Python 应用的方式。单阶段镜像会把 gcc、python-dev、.so 编译中间件全塞进去，体积翻倍，还带安全隐患。
选对基础镜像，避开 glibc 兼容雷区
别用 Alpine。很多 Python 包的预编译 wheel 依赖 glibc，而 Alpine 用的是 musl libc，强行安装容易报 ImportError: xxx.so: cannot open shared object file。稳妥做法是：
- build stage 和 runtime stage 都用同源 Debian slim 镜像，比如
python:3.11-slim-bookworm - 确认系统版本一致：bookworm 对 bookworm，bullseye 对 bullseye，避免 libc 版本错配
- 如果项目依赖特定系统库（如
libonnxruntime或librknn），在 build stage 安装它们，在 runtime stage 用COPY --from=builder精确复制对应 .so 文件
用 wheel 预编译替代运行时 pip install
runtime 阶段禁止执行 RUN pip install——这会让 pip 缓存、.dist-info、临时文件残留，失去多阶段意义。正确流程是：
- 在 builder 阶段：先装系统依赖（
gcc libc6-dev），再用pip wheel --no-deps --wheel-dir /wheels -r requirements.txt下载并编译所有 wheel - 把编译好的
.whl文件和需要的系统 .so（如/usr/lib/x86_64-linux-gnu/libonnxruntime.so）一并保留 - runtime 阶段只用
pip install --no-cache-dir --find-links /wheels --no-index离线安装，不联网、不编译、不留缓存
COPY 要精准，别拷整个 site-packages 目录
常见错误是写 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/（末尾斜杠表示“内容复制”，不是目录覆盖） - 额外系统库也按需复制：
COPY --from=builder /usr/lib/x86_64-linux-gnu/libonnxruntime.so /usr/lib/x86_64-linux-gnu/ - 用
ldd your_module.so检查缺失依赖，缺哪个就补哪个，不盲目拷全系统 lib 目录
验证镜像是否真正独立
构建完后进容器检查，确保它不依赖构建环境：
- 运行
docker run --rm -it your-image ldd /usr/local/lib/python3.11/site-packages/xxx.cpython-*.so | grep "not found"，无输出才安全 - 执行
pip list，只显示业务依赖，没有setuptools、wheel、pip等构建工具 - 对比镜像大小：含 PyTorch 的镜像，多阶段通常压到 500–700MB；单阶段常超 1.2GB
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
