在 docker-compose.yml 中安全引用系统级环境变量需明确插值与注入区别：系统变量仅用于配置文件占位符替换，须显式声明（如 - db_host=${db_host}）才能注入容器；推荐方式包括显式转发加默认值、env_file 分离敏感项、--env-file 启动覆盖；禁用未定义变量直接引用、误用 .env 文件及非法块语法；验证用 docker-compose config 查看最终生效配置。
在 docker-compose.yml 中安全引用系统级环境变量，关键在于明确“引用”和“注入”的区别：系统级环境变量（即宿主机 shell 中 export 的变量）默认**只参与配置文件的变量插值**，不会自动进入容器。要让它们真正生效于容器内，必须显式声明或传递。
明确变量作用域：插值 ≠ 注入
系统级环境变量（如 export DB_HOST=192.168.1.10）在运行 docker-compose up 时会被读取，但仅用于替换 docker-compose.yml 中的 ${VAR} 占位符——比如镜像名、端口映射、服务依赖名等。它本身不会自动变成容器内的环境变量。
例如：
- DB_URL=postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/app
这里 ${DB_HOST} 是从 shell 读取并做字符串替换，最终生成的是一个静态字符串值传给容器；而 DB_HOST 这个键本身并不会作为独立环境变量出现在容器里，除非你额外写一行 - DB_HOST=${DB_HOST}。
安全引用的三种推荐方式
-
显式转发 + 默认值兜底：在
environment下逐个声明，并用${VAR:-default}防止未设置时报错
例：- DB_USER=${DB_USER:-admin}、- API_TIMEOUT=${API_TIMEOUT:-30000} -
用
env_file分离敏感项：把系统级变量导出到临时 env 文件（如/tmp/runtime.env），再通过env_file加载
避免硬编码，也规避了 shell 变量被意外清空的风险 -
启动时用
--env-file覆盖：不依赖 shell 环境，直接指定文件路径，更可控、可审计
例：docker-compose --env-file ./prod.env up -d，该文件可由 CI/CD 动态生成
必须避开的高危操作
- 不要在
docker-compose.yml中直接写environment: [ "DB_PASSWORD=$DB_PASSWORD" ]—— 若 shell 未定义该变量，会注入空字符串，极易导致认证失败 - 不要把
.env当作系统级变量载体：它只在 compose 解析阶段起作用，且容易被误提交到 Git；系统级变量应来自运行时上下文，而非项目根目录文件 - 避免使用
environment: >块语法批量导入 shell 变量——Docker Compose 不支持该写法，会导致解析错误
验证是否生效的可靠方法
运行前执行：docker-compose config
它会输出最终解析后的完整配置（含所有变量展开结果），可直观看到 environment 列表中实际注入了哪些键值对。这是判断系统变量是否被正确引用和传递的黄金标准。
