使用Poetry与多阶段Docker镜像时遇ModuleNotFoundError问题排查

1. 依赖未正确声明或安装 #

• 原因：yaml模块实际由pyyaml包提供，若pyproject.toml未声明该依赖，或构建阶段未完整安装依赖，会导致模块缺失。
• 解决措施：
  • 在pyproject.toml的[tool.poetry.dependencies]区块添加：pyyaml = "^6.0"（版本号可按需调整）。
  • 构建阶段执行poetry install时，使用--no-root --no-dev（无需开发依赖时），并保留poetry.lock保证依赖一致性，Dockerfile示例：

    RUN poetry install --no-root --no-dev
    

  • 重新构建时加--no-cache参数规避缓存干扰：docker build --no-cache -t your-image-name .

2. 多阶段构建虚拟环境复制不完整或路径不一致 #

• 原因：复制.venv时遗漏文件，或构建/运行阶段虚拟环境路径不同，导致Python无法识别依赖。
• 解决措施：
  • 构建阶段先执行poetry config virtualenvs.in-project true，确保虚拟环境生成在项目目录内，再完整复制到运行阶段：

    # 构建阶段
    WORKDIR /app
    RUN poetry config virtualenvs.in-project true
    RUN poetry install --no-root --no-dev
    
    # 运行阶段
    FROM python:3.10-slim
    WORKDIR /app
    COPY --from=builder /app/.venv /app/.venv
    

3. 虚拟环境未正确激活或路径优先级冲突 #

• 原因：系统Python可能优先于虚拟环境Python被调用，即使设置了PATH也可能出现识别问题。
• 解决措施：
  • 运行阶段在复制.venv后设置环境变量：

    ENV PATH="/app/.venv/bin:$PATH"
    

  • 运行容器时直接调用虚拟环境内的Python：

    docker run your-image-name /app/.venv/bin/python main.py
    

  • 进入容器后执行/app/.venv/bin/pip list，检查pyyaml是否存在，若不存在则查看构建日志排查依赖安装失败原因。

4. Python版本不匹配 #

• 原因：构建与运行阶段使用的Python镜像版本不同，虚拟环境依赖与运行环境不兼容。
• 解决措施：
  • 确保构建和运行阶段使用相同版本的Python基础镜像，例如：

    # 构建阶段
    FROM python:3.10-slim as builder
    
    # 运行阶段
    FROM python:3.10-slim
    

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