容器与云原生 / 系统课时

环境变量为什么没有生效

环境变量为什么没有生效

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:

text
APP_MODE=staging

再准备给容器使用的 app.env:

text
APP_MODE=from-env-file
API_URL=https://api.example.test

compose.yaml 同时使用两种来源。$$APP_MODE 中的双美元符号用于把字面量 $APP_MODE 留给容器里的 shell,而不是让 Compose 提前插值:

yaml
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 用于插值的值,再运行一次临时容器观察真正的运行时环境:

bash
docker compose config --environment | grep '^APP_MODE='
docker compose run --rm demo

预期输出

首次运行可能额外出现镜像拉取或网络创建信息;关键输出应为:

text
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。可以用一次临时赋值验证:

bash
APP_MODE=production docker compose run --rm demo

预期输出

text
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 解析时拿到什么,再确认服务配置准备注入什么,最后确认新建容器实际收到什么。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

环境变量为什么没有生效

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通