docker compose 通过 .env 文件、env_file 字段和 --env-file 参数分层管理环境变量,优先级为命令行 > environment > env_file > .env > shell 环境,推荐用 .gitignore 排除敏感变量文件并避免明文存储密钥。

Docker Compose 使用环境变量文件管理配置,核心是把配置值从 docker-compose.yml 中抽离出来,用纯文本 .env 或自定义 .env.xxx 文件统一维护,既安全又便于多环境切换。
直接读取项目根目录的 .env 文件
Compose 启动时会自动查找并加载当前目录下的 .env 文件(无需在 YAML 中声明)。这个文件适合放通用默认值,比如:
WEB_PORT=8080 DB_HOST=localhost LOG_LEVEL=info
然后在 docker-compose.yml 中通过 ${KEY} 插值引用:
services:
web:
image: nginx
ports:
- "${WEB_PORT}:80"
db:
image: postgres
environment:
POSTGRES_DB: myapp
POSTGRES_PASSWORD: "${DB_PASSWORD:-default123}"
注意:${DB_PASSWORD:-default123} 表示若该变量未设置,使用默认值 default123 —— 这对开发环境很实用。
为不同环境指定独立的环境文件
用 env_file 字段可为某个服务加载专属变量文件,支持多个文件按顺序加载,后加载的同名变量会覆盖前面的:
services:
app:
image: myapp:latest
env_file:
- .env.common
- .env.staging
其中 .env.common 定义基础项,.env.staging 覆盖或补充 staging 环境专用值(如 API_URL=https://api.staging.example.com)。
运行时动态指定环境文件
启动时用 --env-file 参数临时注入变量,优先级高于 .env 和 env_file:
docker compose --env-file .env.prod up -d
它只影响本次运行,不修改配置文件,适合 CI/CD 流水线或临时调试。
环境变量加载优先级(由高到低)
- 命令行
-e KEY=VALUE或--env-file -
docker-compose.yml中environment:显式定义的变量 -
env_file:加载的文件内容 - 项目根目录
.env文件 - 宿主机 Shell 环境变量(如
export DB_PORT=5433)
安全提醒
不要在 .env 或 env_file 中存放密码、密钥等敏感信息。这些文件容易被误提交到 Git。真正敏感的内容应通过 Docker Secrets(Swarm 模式)或外部密钥管理服务(如 HashiCorp Vault)注入,或至少用 .gitignore 排除 .env.* 文件。
变量文件格式要严格:KEY=VALUE,等号两侧不能有空格;# 开头为注释;空行忽略;值含空格需加引号(如 APP_NAME="My App")。











