环境变量如何在 compose.yml 中设置默认兜底参数

Docker Compose中设置环境变量默认值的核心是${VAR:-default}语法，当VAR未定义或为空时使用default；该语法适用于environment字段，冒号后不可有空格，且空字符串也会触发兜底。

在 compose.yml 中设置环境变量的默认兜底值，核心是用 ${VAR:-default} 语法 —— 这是 Docker Compose 支持的 Shell 风格变量展开，当环境变量未定义或为空时，自动使用默认值。

直接在 service 的 environment 下写兜底值

这是最常用的方式。在 environment 列表中，对每个变量显式指定带默认值的表达式：

services:app:image: myapp:latestenvironment:- DATABASE_URL=${DATABASE_URL:-sqlite:///app.db}- LOG_LEVEL=${LOG_LEVEL:-info}- DEBUG=${DEBUG:-false}

注意：冒号后面不能有空格；:- 是固定语法；如果变量本身设为空字符串（DATABASE_URL=""），该语法仍会触发兜底（即认为空）。

用 env_file 提前加载并支持兜底

如果变量较多，可配合 .env 文件 + env_file 使用，但要注意：env_file 不支持兜底语法，它只做键值加载。兜底逻辑仍需写在 environment 或服务配置里：

1. 先在 .env 中写基础变量（如 PORT=8000），不写兜底
2. 在 compose.yml 中继续用 ${PORT:-3000} 覆盖或补充
3. 这样既复用文件，又保留运行时兜底能力

避免常见坑：空字符串 vs 未设置

Docker Compose 对 ${VAR:-default} 的判断逻辑是：只要 VAR 在 shell 环境中被声明（哪怕值为空），就不触发兜底。所以：

1. 在终端执行 export API_KEY="" 后再运行 docker compose up，${API_KEY:-missing} 仍为空，不会变成 missing
2. 真正“未设置”是指 unset API_KEY 或根本没 export 过
3. 若需强制兜底（包括空字符串场景），建议在应用启动脚本里二次处理，或改用 ${VAR:+value} / ${VAR:-} 组合判断

进阶：用 x-* 扩展字段统一管理默认值

利用 Compose 的自定义扩展（x-defaults）可提高可维护性，虽不被引擎解析，但方便团队约定和工具读取：

x-defaults:env:DATABASE_URL: sqlite:///app.dbLOG_LEVEL: info
services: app: image: myapp:latest environment:

DATABASE_URL=${DATABASE_URL:-${x-defaults.env.DATABASE_URL}}
LOG_LEVEL=${LOG_LEVEL:-${x-defaults.env.LOG_LEVEL}}

注意：这需要配合外部工具（如 yq、自定义脚本）预处理，原生 Compose 不解析 x-* 字段，纯属约定增强可读性。