FastAPI Docker容器无法读取.env文件变更问题求助

问题场景 #

在使用Docker Compose管理容器时，遇到以下异常：

• 在工作区.env文件新增环境变量后，删除容器、镜像并通过--no-cache重建，进入容器执行echo $VARIABLE_NAME返回空值，但原有两个变量正常生效
• 重命名旧.env为.envOLD并创建含新值的.env，重启Docker后重新构建启动容器，执行echo命令仍返回旧变量值，而非新.env中的内容

核心解决方案 #

1. 在docker-compose.yaml中声明新环境变量

Docker Compose只会将docker-compose.yaml里明确引用的.env变量注入容器。如果是新增的变量，必须在配置文件中添加对应引用：

services:
  your-service-name:
    environment:
      - FIRST_VAR=${FIRST_VAR}
      - SECOND_VAR=${SECOND_VAR}
      - THIRD_VAR=${THIRD_VAR}  # 新增变量必须添加此行，否则Docker不会加载

2. 让Docker Compose重新读取.env并重启容器

修改.env后，仅删除容器或镜像无法让新配置生效，需要执行完整的重启命令：

# 先停止并移除容器、网络
docker-compose down
# 重新构建镜像（--no-cache确保不使用旧缓存）并启动容器
docker-compose up --build --no-cache

注意：执行命令时要确保当前工作目录是.env文件所在的目录，否则Docker Compose会读取其他位置的.env或使用默认配置。

额外排查要点 #

• 检查全局.env文件干扰：Docker Compose会优先读取当前目录的.env，但如果用户根目录或其他全局路径存在.env文件，可能会覆盖局部配置。可以执行docker-compose config命令查看最终生效的变量值，确认是否与新.env一致。
• 排查Dockerfile硬编码变量：如果Dockerfile中使用ENV指令硬编码了变量值，即使更新.env，镜像构建时仍会使用旧值。这种情况需要删除Dockerfile中的硬编码ENV，改用docker-compose.yaml的environment字段注入变量。
• 清理残留缓存与卷：若上述操作仍无效，可清理Docker残留资源：

  # 删除容器的同时移除关联的数据卷
  docker-compose down -v
  # 清理所有未使用的镜像、容器、网络和卷
  docker system prune -f
  

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