变量替换失败是docker-compose up -d启动失败的隐蔽原因，源于.env文件编码/bom、空格、命名不规范或引用方式错误，需通过docker-compose config验证替换结果，并区分${var}（yaml解析）、env_file（容器环境）、build.args（构建阶段）三类作用域。
变量替换失败是 docker-compose up -d 启动失败的隐蔽原因——它不报语法错误，但服务会因空值、错值或路径失效而静默崩溃。排查核心在于确认变量是否真正加载、是否被正确引用、是否在运行时有效。
检查 .env 文件格式与加载状态
.env 是默认加载的环境文件，但极易因格式问题失效：
- 必须是 UTF-8 编码且无 BOM（Windows 记事本保存易带 BOM，建议用 VS Code 或 vim 编辑）
- 等号两侧不能有空格：✅
DB_HOST=localhost，❌DB_HOST = localhost - 变量名仅支持字母、数字、下划线；以数字开头会解析失败
- 注释必须独占一行，用
#开头，不可写在行尾
验证是否加载成功：运行 docker-compose config，输出中所有 ${VAR} 应已被替换成实际值；若仍显示 ${DB_HOST}，说明变量未加载或名称不匹配。
确认变量引用方式与作用域
Compose 中变量有三种使用场景，规则不同：
-
在 docker-compose.yml 中用
${VAR}：只从.env或 shell 环境读取，environment:块内也可用，但env_file:加载的文件不参与此替换 -
env_file:指定的文件：内容直接注入容器环境，不影响 compose 文件本身的变量解析，也不用于镜像构建阶段 -
build:下的args:：需显式声明args: [VAR]，且变量必须来自.env或命令行--build-arg，Dockerfile 中用ARG VAR接收
常见陷阱：误以为 env_file: .env 能让 ${VAR} 在 yaml 中生效——其实不能，它只影响容器内环境。
验证运行时变量是否生效
即使 compose 解析成功，容器内应用也可能拿不到变量：
- 启动后进入容器：
docker-compose exec web sh，再执行printenv | grep VAR，确认变量是否存在、值是否正确 - 若变量为空，检查是否拼写不一致（如
.env写API_URL，yaml 中写${api_url}—— 区分大小写） - 若值含特殊字符（如
/、$、空格），务必用引号包裹：command: ["sh", "-c", "echo ${LOG_PATH}"]→ 改为command: sh -c 'echo "$${LOG_PATH}"'（注意双 $ 防止 shell 提前解析）
调试技巧：强制暴露变量解析过程
在服务中加临时诊断命令，直观看到变量是否就位：
- 修改服务的
command：
command: sh -c 'echo "DB_HOST=${DB_HOST:-NOT_SET}"; echo "PORT=${PORT:-MISSING}"; exec nginx -g "daemon off;"'
- 启动后立刻查日志：
docker-compose logs web | head -n 10，输出会清晰显示每个变量的实际值或默认值 - 该方法能快速区分是 compose 解析失败，还是容器内应用读取逻辑出错
