多阶段Docker构建中复制Python虚拟环境异常问题排查

问题描述 #

采用Docker多阶段构建，第一阶段在virtualenv中安装依赖，第二阶段复制已构建的虚拟环境，但第二阶段出现以下异常：

• 执行pip freeze无输出
• 无法正常运行Daphne服务器
• 仅Python Shell能导入依赖，外部命令无法识别已安装包

核心原因 #

第二阶段先执行RUN python3 -m venv $VIRTUAL_ENV创建新虚拟环境，再复制第一阶段的虚拟环境内容覆盖，导致虚拟环境内的脚本（如pip、python）保留了第一阶段的硬编码路径（第一阶段虚拟环境路径为/.venv，第二阶段为/opt/venv）。当执行pip等命令时，脚本会尝试调用不存在的/.venv/bin/python，最终 fallback 到无对应依赖的系统Python，因此出现无输出、服务无法启动的问题。

修复方案 #

修正后的Dockerfile #

FROM python:3.11-slim-bullseye AS venv-image
RUN apt-get update && apt-get -y install libpq-dev gcc
COPY poetry.toml poetry.lock pyproject.toml entrypoint.sh ./
ENV VIRTUAL_ENV=/.venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
RUN python3 -m venv $VIRTUAL_ENV
RUN pip install poetry && poetry install

FROM python:3.11-slim-bullseye as app-image
EXPOSE 80
WORKDIR /app
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
# 移除第二阶段创建虚拟环境的步骤，直接复制第一阶段的完整虚拟环境
COPY --from=venv-image /.venv $VIRTUAL_ENV
COPY . /app

ENTRYPOINT ["bash", "entrypoint.sh"]

额外优化建议 #

1. 依赖安装验证：第一阶段中，由于已设置PATH指向虚拟环境，pip install poetry和poetry install都会直接作用于该虚拟环境，无需额外配置。
2. 命令调用规范：在entrypoint.sh或容器内执行命令时，建议使用绝对路径（如/opt/venv/bin/python、/opt/venv/bin/daphne），避免路径解析异常。
3. 有效性校验：进入容器后，可执行/opt/venv/bin/pip freeze查看依赖是否正确复制；或执行which python，确认输出为/opt/venv/bin/python。

内容的提问来源于stack exchange，提问作者kirill ras