容器与云原生 / 系统课时
环境变量为什么没有生效
环境变量为什么没有生效
Compose 中“环境变量没生效”通常不是变量不存在,而是把 Compose 配置插值和容器运行时环境混在了一起。排查时要分别确认变量从哪里读取、最终 Compose 配置是什么,以及容器实际拿到了什么值。
学习目标
- 区分 Compose 插值变量与容器内部环境变量
- 能判断
.env、--env-file、environment、env_file等来源的作用位置 - 能用解析后的配置和容器实际输出定位覆盖问题
先区分两层变量
第一层是 Compose 配置插值。像 image: "app:${TAG}" 或 APP_MODE: "${APP_MODE}" 里的 ${...},会在 Compose 解析 YAML 时替换。常见来源是当前 shell、命令行指定的 --env-file,以及默认加载的 .env。
第二层是 容器运行时环境。只有服务配置或镜像明确提供的变量,才会形成容器内可读取的环境。把 FOO=bar 写进项目根目录 .env,并不等于容器里自动出现 FOO。
| 来源 | 主要作用位置 | 会单独自动进入容器吗 |
|---|---|---|
shell、.env、--env-file |
为 Compose 的 ${VAR} 提供插值值 |
否 |
environment |
服务容器环境 | 是 |
服务级 env_file |
服务容器环境 | 是 |
Dockerfile ENV |
镜像默认环境 | 是,但可被 Compose 覆盖 |
docker compose run -e |
一次性运行容器 | 是,仅影响该次运行 |
排障时最常用的两个覆盖关系是:Compose 插值时当前 shell 高于环境文件;同一个服务里,environment 会覆盖 env_file 中的同名变量。
用一个最小例子看清覆盖
先准备项目根目录的 .env:
APP_MODE=staging再准备给容器使用的 app.env:
APP_MODE=from-env-file
API_URL=https://api.example.testcompose.yaml 同时使用两种来源。$$APP_MODE 中的双美元符号用于把字面量 $APP_MODE 留给容器里的 shell,而不是让 Compose 提前插值:
services:
demo:
image: alpine:3.20
env_file:
- app.env
environment:
APP_MODE: "${APP_MODE:-development}"
command:
- sh
- -c
- 'printf "APP_MODE=%s\nAPI_URL=%s\n" "$$APP_MODE" "$$API_URL"'先看 Compose 用于插值的值,再运行一次临时容器观察真正的运行时环境:
docker compose config --environment | grep '^APP_MODE='
docker compose run --rm demo预期输出
首次运行可能额外出现镜像拉取或网络创建信息;关键输出应为:
APP_MODE=staging
APP_MODE=staging
API_URL=https://api.example.test第一行说明 Compose 从 .env 得到 APP_MODE=staging;后两行来自容器。虽然 app.env 里也写了 APP_MODE=from-env-file,但 environment 中已经给出同名变量,所以容器最终得到 staging。API_URL 没有被 environment 覆盖,因此仍来自 app.env。
从最终值反推来源
如果 shell 中已经存在同名变量,它会参与 Compose 插值并覆盖 .env。可以用一次临时赋值验证:
APP_MODE=production docker compose run --rm demo预期输出
APP_MODE=production
API_URL=https://api.example.test因此,看到变量值“不对”时,不要只打开 .env 检查。先用 docker compose config --environment 看插值输入,再用 docker compose config 看解析后的服务配置,最后进入或运行容器确认真实环境。这样可以把问题明确落在“读取错来源”“被更高优先级覆盖”或“容器没有重建”中的一种。
别用 restart 期待刷新变量
环境变量是在容器创建阶段写入配置的。修改 .env、env_file 或 environment 后,docker compose restart 只重启现有容器,不会把新的服务配置重新写进去。
应重新执行 docker compose up -d 让 Compose 根据配置变化重建服务;如果需要明确排除旧容器配置影响,可以使用 docker compose up -d --force-recreate <SERVICE>。重建后再用 docker compose exec <SERVICE> env 检查目标变量,而不是只根据应用日志猜测。
把这两层分开后,排查顺序就很稳定:先确认 Compose 解析时拿到什么,再确认服务配置准备注入什么,最后确认新建容器实际收到什么。