容器与云原生 / 系统课时

.env 文件到底影响什么

.env 文件到底影响什么

.env 最容易被误解成“自动塞进容器的环境变量文件”。本课用一个可验证的小例子拆开两条链路:Compose 如何读取 .env 做变量替换,以及这些值在什么条件下才会真正进入容器。

学习目标

  • 说明 .env 在 Compose 变量插值中的作用
  • 区分“Compose 配置变量”和“容器环境变量”
  • 使用 docker compose config 验证变量来源与替换结果

.env 先影响 Compose 配置

Compose 处理 compose.yaml 时,可以把 ${VAR} 替换成外部值。默认 .env 的核心作用,就是为这一步提供变量来源;它可以改变镜像标签、端口、卷路径,也可以被 environment 再引用。.env 中出现某个键,并不等于容器里自动拥有同名环境变量。([Docker Documentation][1])

.env、Compose 插值与容器环境变量的关系

例如,下面的 .env 同时提供镜像、宿主机端口和应用模式三个值,其中前两个只用于生成 Compose 模型,APP_MODE 则被 environment 显式传给容器。

bash
mkdir -p compose-env-demo
cd compose-env-demo

cat > .env <<'EOF'
WEB_IMAGE=nginx:1.27-alpine
HOST_PORT=8080
APP_MODE=development
EOF

cat > compose.yaml <<'EOF'
services:
  web:
    image: "${WEB_IMAGE}"
    ports:
      - "${HOST_PORT}:80"
    environment:
      APP_MODE: "${APP_MODE}"
EOF

# 避免当前 Shell 中的同名变量覆盖演示用 .env
unset WEB_IMAGE HOST_PORT APP_MODE

docker compose config --environment | grep -E '^(APP_MODE|HOST_PORT|WEB_IMAGE)=' | sort

预期输出

text
APP_MODE=development
HOST_PORT=8080
WEB_IMAGE=nginx:1.27-alpine

docker compose config --environment 用来查看 Compose 插值时实际采用的环境;若想看变量替换后的完整 Compose 模型,则运行 docker compose config。([Docker Documentation][1])

为什么 .env 不等于容器环境

可以把过程理解为两个阶段:先生成配置,再创建容器。${WEB_IMAGE} 和 ${HOST_PORT} 在第一阶段就已经变成镜像名和端口映射;只有 environment.APP_MODE 明确要求把值写入容器环境,所以应用进程才能读取 APP_MODE。

如果从 compose.yaml 中删除 environment 段,.env 仍然可以继续替换镜像和端口,但容器不会仅因为 .env 中存在 APP_MODE=development 就自动获得这个变量。Docker 官方文档也明确区分了 Compose 插值与容器环境设置。([Docker Documentation][2])

同名变量从哪里取值

对 Compose 插值而言,同名变量存在多个来源时,常用优先级是:当前 Shell 环境最高,其次是命令行指定的 --env-file,未指定时再使用项目目录中的 .env。这意味着本地终端里已经导出的变量可能覆盖 .env,排查时不要只盯着文件内容。([Docker Documentation][1])

来源 典型用途 相对优先级
Shell 环境 临时覆盖、CI 注入 高
--env-file 指定文件 切换开发、测试、生产配置 中
项目 .env 项目默认插值值 低

对必须存在的配置,可以使用 ${VAR:?error} 让 Compose 在变量缺失时直接报错;对允许默认值的配置,可以使用 ${VAR:-default}。这样比变量缺失后得到空字符串更容易定位问题。([Docker Documentation][1])

什么时候用 .env

.env 很适合保存非敏感的部署参数,例如镜像标签、宿主机端口、功能模式或 Compose 自身的项目配置。需要把某个值交给容器应用时,再通过 environment 或服务级 env_file 明确传入。

判断一个变量“影响了哪里”时,先问它是否只参与 ${...} 插值,再看服务是否通过 environment 或 env_file 把它传进容器。把这两步分开,绝大多数 .env 混淆都会消失。

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

目录与阅读设置

阅读设置

17

记录一个想法

.env 文件到底影响什么

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

登录哪都通