项目级 .env 是什么
Compose 会在项目目录下寻找名为 .env 的文件，用它为编排文件里的变量占位符提供取值，例如镜像标签、端口号、域名等都可以写成 ${TAG} 由这个文件注入。要点是它只参与 Compose 自己解析文件时的替换，不会自动进入容器。变量来源有优先级：当前 shell 里的环境变量会盖过 .env 里的同名项，这也是 CI 上覆盖默认值的常用手段。
基本信息
| 默认位置 | 执行 compose 命令时的项目目录下 .env |
|---|---|
| 引用语法 | ${TAG}、${TAG:-默认值}、${TAG:?必须提供} |
| 优先级 | shell 环境变量 > .env 文件 |
| 换文件 | docker compose --env-file .env.prod config / up |
| 与 env_file 区别 | env_file 决定容器内的环境变量，.env 只供文件插值 |
| 验证命令 | docker compose config 渲染出替换后的最终配置 |
典型使用场景
- 不同环境用不同镜像标签：本地 .env 写开发标签，CI 用环境变量覆盖为发布版本
- 集中管理端口与域名，避免在多处硬编码
- 把敏感值留在本机 .env 并加入忽略清单，仓库里只放示例文件
- 用 ${VAR:?} 形式让缺失的必填配置直接报错，避免带着空值部署
- 排查变量不生效：渲染最终配置看实际取值
声明与使用
声明与使用
services:
api:
image: app/api:${TAG:-1.4.2} # 缺省值：未提供时用 1.4.2
ports:
- "${API_PORT:-8080}:8080"
environment:
LOG_LEVEL: ${LOG_LEVEL:-info} # 需要传进容器必须显式引用
db:
image: postgres:16-alpine
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD:?必须提供数据库口令}环境与验证
环境与验证
# .env 写本地默认值，仓库里只保留 .env.example
cat >> .env <<'EOF'
TAG=1.4.2-dev
API_PORT=8080
EOF
# shell 变量优先级更高，适合在 CI 里覆盖
TAG=1.4.3 docker compose config --services
# 指定其他文件，多环境切换不必改目录
docker compose --env-file .env.prod config | head -30
# 查看渲染结果，确认变量替换符合预期（注意别把含密钥的输出贴到公开渠道）
docker compose config变量来源与生效范围
| 来源 | 影响对象 | 优先级 |
|---|---|---|
| shell 环境变量 | Compose 插值 | 最高 |
| 项目 .env | Compose 插值 | 中 |
| --env-file 指定文件 | Compose 插值 | 替代 .env |
| env_file 字段 | 容器内环境变量 | 服务级 |
| environment 字段 | 容器内环境变量 | 覆盖 env_file |
| 镜像内 ENV | 容器默认值 | 最低 |
.env 里的变量不会自动进容器：要在 environment 或 env_file 里显式引用。这一点最容易混淆，排查「容器里读不到变量」时先确认走的是哪条链路。
.env 常被用来存放口令与密钥，务必加入版本控制的忽略清单，仓库里只保留不带真实值的示例文件，避免凭据随代码外泄。