变量替换失败是 Docker Compose 启动阶段最隐蔽也最常被误判的问题，根源在于环境变量未正确解析、注入或被高优先级来源覆盖，需通过 docker-compose config 检查未定义变量、确保 .env 文件格式规范、明确作用域与优先级，并避免嵌套插值。
变量替换失败是 docker compose 启动阶段最隐蔽也最常被误判的问题——表面报错可能是“service failed to start”或“invalid reference format”，但根源往往藏在环境变量未正确展开的细节里。关键不在报错信息本身，而在变量是否真的被解析、是否按预期注入、是否被更高优先级来源覆盖。
变量未定义导致解析中断
当 docker-compose.yml 中出现 ${MISSING_VAR}，而该变量既未在 .env 文件中声明，也未在 shell 中 export，Compose 会直接报错退出（如 "undefined variable 'MISSING_VAR'"），而不是静默留空。
- 检查方式：运行 docker-compose config，它会在加载阶段立即暴露未定义变量
- 修复方法：为所有可选变量显式加默认值，例如 DB_PORT=${DB_PORT:-5432}
- 注意：${VAR-default} 和 ${VAR:-default} 行为不同——后者在 VAR 为空字符串时也生效，前者仅在 VAR 未设置时生效
.env 文件未被识别或格式错误
.env 文件必须位于 docker-compose.yml 所在目录，且文件名严格为 .env（不能是 .env.local 或 env.txt）。常见失效原因包括：
- 文件编码含 BOM（尤其 Windows 编辑器保存时）→ 用 file .env 检查，推荐用 VS Code 以 UTF-8 无 BOM 保存
- 等号前后有空格 → 错误写法：DB_USER = admin；正确写法：DB_USER=admin
- 变量值含特殊字符未引号包裹 → 如 API_KEY=abc$123 中 $ 会被 shell 解析 → 应写为 API_KEY="abc\$123" 或使用单引号
环境变量作用域混淆
很多人误以为 .env 文件中的变量会自动注入容器环境，其实它只用于 compose 文件自身的变量替换（比如 image: myapp:${TAG}），不会自动出现在容器的 printenv 输出里。
- 若需传入容器，请显式写入 environment 或 env_file 字段
- build.args 中的变量（如构建参数 NODE_ENV）不会继承 runtime 的 environment，必须单独传递
- 同一变量在多个位置定义时，优先级从高到低为：命令行 -e > compose 文件 environment > env_file > .env 文件 > 宿主机环境
嵌套与动态变量语法不支持
Docker Compose 原生不支持类似 ${${ENV}_SUFFIX} 或 ${ENV:-${FALLBACK}} 这类嵌套插值，遇到即报错。
- 替代方案一：用脚本预生成最终 compose.yml（如用 envsubst 或 yq 工具）
- 替代方案二：将组合逻辑前置到 .env 文件中，例如定义 CONFIG_ENV=prod 和 CONFIG_FILE=config-${CONFIG_ENV}.yml，再在 compose 中引用 ${CONFIG_FILE}
- 切勿依赖 Bash 的数组、命令替换等高级特性——Compose 解析器不具备 shell 执行能力
