Docker Compose 仅在启动时读取项目根目录下的 `.env` 文件，且环境变量需显式声明在 `docker-compose.yml` 中才会注入容器；修改 `.env` 后必须重新运行 `docker-compose up`（而非仅重建镜像），否则旧值仍会被缓存使用。

在 FastAPI 项目中使用 Docker 容器化部署时，许多开发者会依赖 .env 文件管理配置（如数据库 URL、密钥等），并期望通过 docker-compose up 自动加载更新。但实际中常遇到「修改 .env 后容器内 echo $VAR 仍显示旧值甚至为空」的问题——这并非 FastAPI 或 Docker 的 Bug，而是由 Docker Compose 的环境变量加载机制导致的。

? 核心机制说明

• .env 文件仅被 docker-compose 进程读取（用于替换 docker-compose.yml 中的 ${VAR} 占位符），不会自动挂载或注入到容器内部；
• 容器内能否访问某个环境变量，取决于 docker-compose.yml 中是否通过 environment 或 env_file 显式声明；
• docker-compose build --no-cache 只重建镜像，不重启容器，也不重新解析 .env；真正触发 .env 重读的操作是 docker-compose up（含 up --build）。

✅ 正确操作步骤

1. 在 docker-compose.yml 中声明变量（推荐使用 environment 显式透传）：

   services:
   api:
    build: .
    environment:
      - DATABASE_URL
      - SECRET_KEY
      - NEW_FEATURE_ENABLED  # ← 新增变量必须在此显式列出
    # env_file: .env  # 不推荐：会将整个文件内容注入，存在安全与覆盖风险

2. 确保 .env 文件位于 docker-compose.yml 同级目录，格式为纯键值对：

   DATABASE_URL=postgresql://user:pass@db:5432/app
   SECRET_KEY=dev-secret-key
   NEW_FEATURE_ENABLED=true

3. 每次修改 .env 后，执行完整重启流程：

   # 停止并移除旧容器（不删镜像也可）
   docker-compose down

重新构建（可选 --no-cache）并启动，强制重读 .env

docker-compose up --build -d

> ⚠️ 注意：`docker-compose up --build` 是关键——仅 `build` 或仅 `up` 都不会刷新环境变量。

### ❌ 常见误区排查
- **误以为 `docker-compose build` 会读 `.env`** → 实际上它只读构建上下文，`.env` 变量需经 `docker-compose.yml` 中转；
- **未在 `environment` 中声明新变量** → 即使 `.env` 已添加，容器内也无法访问；
- **使用 `env_file: .env` 但路径错误或权限受限** → 推荐优先用 `environment` + `.env` 替换方式，更可控；
- **在容器内修改 `.env` 文件** → 容器内 `.env` 对宿主机无影响，且重启后丢失（应始终修改宿主机上的 `.env`）。

### ? 补充建议：开发环境快速验证
可在 `docker-compose.yml` 中临时加入调试命令，确认变量是否生效：
```yaml
command: sh -c "echo 'DB: $$DATABASE_URL' && echo 'NEW: $$NEW_FEATURE_ENABLED' && uvicorn app.main:app --host 0.0.0.0:8000"

注意：$$ 是 YAML 中转义 $ 的写法，确保变量在容器启动时展开。

总结来说，Docker Compose 的环境变量传递是“静态声明 + 启动时注入”模型。保持 .env 与 docker-compose.yml 声明一致，并坚持 down + up --build 流程，即可彻底解决变量不更新问题。