Docker多阶段构建Python项目：.py文件删除后仍残留至生产镜像问题

你的核心问题是：builder阶段明明删除了所有.py源文件，但最终生产镜像中仍存在这些文件。以下是可能的原因和对应的解决办法：

可能的原因1：Docker层缓存导致删除命令未执行 #

如果Docker复用了之前构建的缓存层，builder阶段的删除命令可能没有实际运行。比如，若COPY ./services/api/ .的层没有变化，Docker会跳过后续的RUN命令（包括删除.py的步骤）。

解决办法： #

构建时强制禁用缓存：

docker build --no-cache -t your-image-name .

可能的原因2：删除命令的路径匹配不完整 #

当前的find命令可能漏掉了某些.py文件，比如：

• 隐藏目录中的.py文件（路径未被-not -path排除）
• 绝对路径与相对路径的匹配偏差
• 其他虚拟环境目录（如./.venv之外的./env等）

解决办法： #

修改删除命令，使用绝对路径并扩大排除范围：

RUN uv run python -m compileall -b -f . && \
    find /usr/src/app -type f -name "*.py" ! -path "*/.venv/*" ! -path "*/venv/*" ! -path "*/env/*" -delete && \
    find /usr/src/app -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true

可能的原因3：builder阶段的验证缺失 #

你注释掉了验证.py文件数量的命令，无法确认builder阶段是否真的删除了所有源码。

解决办法： #

在builder阶段添加强制验证步骤，确保删除彻底：

# 编译并删除源码
RUN uv run python -m compileall -b -f . && \
    find /usr/src/app -type f -name "*.py" ! -path "*/.venv/*" ! -path "*/venv/*" -delete && \
    find /usr/src/app -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true

# 验证所有非虚拟环境的.py文件已被删除，否则构建失败
RUN if [ $(find /usr/src/app -type f -name "*.py" ! -path "*/.venv/*" ! -path "*/venv/*" | wc -l) -ne 0 ]; then \
        echo "ERROR: Python source files still exist!" && exit 1; \
    fi

额外优化建议 #

1. 合并RUN命令：将编译、删除、验证步骤合并为一个RUN命令，减少Docker层数量，同时避免缓存问题。
2. 设置PYTHONPATH：在production阶段添加环境变量，确保Python能找到编译后的.pyc模块：

   ENV PYTHONPATH=/usr/src/app/src
   

3. 简化production阶段的重复命令：production阶段的RUN apt-get update ...和deps阶段完全重复，可以直接从deps阶段继承，避免重复安装：

   FROM deps as production
   WORKDIR /usr/src/app
   # 无需重复执行apt-get安装，直接从deps继承已安装的工具
   COPY --from=builder /usr/src/app .
   ENV PYTHONPATH=/usr/src/app/src
   CMD uv run --no-sync python -m emu.entrypoints.api
   

内容的提问来源于stack exchange，提问作者elyana quah