相同Dockerfile下Docker CLI构建正常但Docker Compose构建失败

核心原因及对应解决方案 #

• Dockerfile指令顺序错误导致路径不匹配
  你当前Dockerfile的执行逻辑是先把本地所有文件复制到镜像默认工作目录（python:3.8-slim-buster基础镜像默认工作目录为/），再切换到/mqtt_api目录执行pip安装。如果你的requirements.txt存放在本地项目根目录而非mqtt_api子目录中，切换工作目录后pip会读取/mqtt_api路径下不完整的依赖列表，导致部分依赖缺失。你单独执行docker run时正常，大概率是故障排查阶段手动在容器内补装了缺失依赖，或者测试使用的镜像并非由当前版本Dockerfile构建。
  修复方案：调整Dockerfile指令顺序，先切换工作目录再复制项目文件：

# syntax=docker/dockerfile:1
FROM python:3.8-slim-buster
WORKDIR /mqtt_api
COPY . .
RUN pip3 install -r requirements.txt
EXPOSE 8000
CMD ["uvicorn", "api:app"]

• Docker Compose 构建缓存未更新
  如果之前修改过Dockerfile或requirements.txt，Docker Compose可能复用了旧的镜像构建层，没有执行最新的依赖安装步骤，导致依赖和当前配置不一致。
  修复方案：执行带无缓存参数的构建命令，强制重新构建所有镜像层：
  docker compose build --no-cache

• 缺失必要环境变量
  你在单独执行docker run命令时传入了自定义环境变量，但当前docker-compose.yaml中没有配置environment字段，部分Python依赖的安装、导入逻辑依赖特定环境变量，缺失时会触发加载失败报错。
  修复方案：在docker-compose.yaml的api服务配置下添加所需环境变量：

api:
    build:
        context: .
        dockerfile: Dockerfile
    container_name: api
    ports:
        - "8000:8000"
    environment:
        - 环境变量名1=变量值1
        - 环境变量名2=变量值2

• .dockerignore规则异常
  检查项目根目录的.dockerignore文件，确认是否配置了排除requirements.txt的规则，导致构建时该文件没有被传入构建上下文，pip安装时无法读取完整依赖列表。

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