docker 容器中环境变量未更新，通常是因为 `.env` 文件仅被 `docker-compose` 解析，而非容器运行时自动重载；必须显式通过 `docker-compose up` 重新启动服务，并确保变量已在 `docker-compose.yml` 中声明。
在 FastAPI 项目中使用 Docker 部署时，许多开发者误以为只要修改本地 .env 文件，容器内就会自动感知并加载新值——但事实并非如此。.env 文件本身不会被容器内的 Python 应用（如 python-dotenv）直接读取，除非你显式在代码中调用 load_dotenv() 且路径正确；更重要的是，在 Docker 场景下，.env 文件的首要作用是为 docker-compose.yml 提供构建/运行时变量替换（即 Compose 的“环境变量插值”），它并不等同于容器内部的运行时环境变量。
✅ 正确做法分两步：
-
在 docker-compose.yml 中显式声明需传递的环境变量
即使 .env 文件中已定义 MY_API_KEY=abc123，你也必须在服务配置中将其注入容器：services: api: build: . environment: - MY_API_KEY=${MY_API_KEY} # ← 关键：从 .env 插值并传入容器 - DATABASE_URL=${DATABASE_URL} # 或使用 env_file（仅适用于静态文件，不支持插值） # env_file: # - .env⚠️ 注意：env_file: [.env] 虽可批量加载，但它仅在容器启动时读取一次，且不会解析 ${VAR} 引用（即不支持变量插值），因此推荐优先使用 environment: [KEY=${KEY}] 方式。
每次修改 .env 后，必须重建并重启容器
docker-compose up --build（或 --no-cache）是必需的——因为 .env 变更会影响 docker-compose.yml 的变量插值结果，进而影响镜像构建参数或容器启动环境。单纯 docker-compose restart 或 docker restart 不会重新解析 .env，也不会触发环境变量更新。
? 验证是否生效？进入容器检查：
docker-compose exec api sh -c 'echo $MY_API_KEY'
若输出为空，请依次排查：
- .env 文件是否位于 docker-compose.yml 同级目录（Compose 默认只读该路径下的 .env）；
- docker-compose.yml 中是否拼写错误（如 MY_API_KRY）；
- 是否执行了 docker-compose down && docker-compose up --build --no-cache（down 清除旧容器状态，--build 强制重建）；
- FastAPI 应用内是否误用 os.getenv("MY_API_KEY") 而未 fallback 到 dotenv 加载（建议统一使用 pydantic-settings 或显式 load_dotenv()）。
? 进阶提示：对于开发热重载场景，可结合 watchmedo + uvicorn reload，但环境变量仍需遵循上述规则——环境变量属于启动态配置，不属于运行时热更范畴。
总结：.env 是 docker-compose 的输入，不是容器的运行时配置源；要让新变量生效，必须「声明 + 重建 + 重启」三者缺一不可。
