如何使用Docker Compose实现Docker化FastAPI应用的自动热重载

核心问题排查方向 #

你当前的docker-compose配置已经添加了--reload参数，不生效的核心原因基本是容器内uvicorn监听的目录和挂载的源码目录不匹配，按以下步骤逐一排查修复即可：

1. 确认Dockerfile中配置了正确的工作目录 #

这是最常见的错误原因，你需要在项目的Dockerfile中明确指定工作目录为挂载的/code路径，示例配置如下：

# 基础镜像示例，可根据你的Python版本调整
FROM python:3.11-slim

# 核心配置：指定容器内工作目录为/code
WORKDIR /code

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 开发环境下可以不复制源码，因为volumes挂载会覆盖该目录，生产环境需要打开
# COPY . .

如果没有指定WORKDIR /code，uvicorn启动时会默认监听容器根目录下的文件，不会检测到/code目录下挂载的本地源码变动。

2. 特殊场景适配 #

• 如果你需要监听.py之外的文件变动（比如html模板、静态资源等），需要修改docker-compose中的启动命令，添加--reload-include参数指定要监听的文件类型：

  command: bash -c "uvicorn main:app --host 0.0.0.0 --port 8000 --reload --reload-include *.html --reload-include *.jinja2"
  

• 如果你是Windows/WSL2环境部署，不要把源码放在Windows挂载的/mnt/c/等路径下，要把代码放到WSL的Linux原生文件系统中，避免文件变更通知延迟/失效。

3. 验证效果 #

修改本地的main.py代码后，查看容器日志，如果出现类似以下日志就说明重载配置已生效：

INFO: Detected file change in 'main.py'. Reloading...

注意：你main.py中if __name__ == '__main__'块里的reload=True不会生效，因为docker-compose指定了启动command，会覆盖默认的入口执行逻辑，该配置不影响功能可以保留。

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