docker-compose config命令是验证Compose配置的唯一可靠第一步，它不启动容器，仅检查YAML语法、解析环境变量、合并多文件配置，输出即表示基本通过，报错则精确定位行列问题。
docker-compose config 命令是唯一可靠的第一步验证
别指望 Docker Desktop 界面里点几下就能发现 YAML 错误——它不会主动校验，也不会高亮缩进问题。真正管用的只有命令行里的 docker-compose config。这个命令不启动任何容器，只做三件事：检查 YAML 语法、解析环境变量（比如 ${DB_HOST}）、合并多文件配置（如 -f docker-compose.yml -f docker-compose.prod.yml）。只要它输出完整配置，就说明语法基本过关；一旦报错，错误信息通常直指某行某列，比如 yaml.scanner.ScannerError 或 found a tab character。
缩进、冒号、引号这三处最容易翻车
YAML 不认 Tab，只认空格；冒号后面必须跟一个空格；含 :、{、[、# 的字符串不加引号会直接解析失败。常见踩坑点：
-
ports下写成- 8080:80（缺引号）→ 应为- "8080:80"，否则可能被当成数字而非映射对 -
environment里写DEBUG=true没问题，但写LOG_LEVEL=debug:verbose就必须加引号：LOG_LEVEL="debug:verbose" -
build:和image:缩进层级不对（比如比服务名少或多两个空格），会导致整个服务被忽略或解析为顶层字段
docker-compose.yml 找不到？先盯住当前路径和文件名
Docker Desktop 默认只在当前工作目录找 docker-compose.yml 或 compose.yml。报 no configuration file provided: not found 时，不是 Docker Desktop 故障，而是你没在对的地方运行命令。确认方式很简单：
- 执行
pwd看当前路径，再用ls -l docker-compose.yml确认文件真实存在 - 文件名拼错（比如写成
docker-compose.yaml或docker_compose.yml）就不认——Docker Compose 只识别那两个标准名 - 如果非要用别的名字或路径，必须显式指定：
docker-compose -f ./prod/compose.yml config
环境变量没生效？检查 .env 文件编码和变量引用格式
Docker Compose 自动加载同目录下的 .env 文件，但它对编码很挑剔：必须是 UTF-8 无 BOM。Windows 记事本保存的 .env 经常带 BOM，导致变量全为空。另外，变量引用必须用 ${VAR_NAME}，不能写成 $VAR_NAME 或 $(VAR_NAME)。还有个隐藏陷阱：docker-compose config 显示的是变量替换后的结果，所以如果看到 image: ${REGISTRY}/app:${TAG} 被展开成空值，说明 .env 里 TAG 没定义，或者定义成了空字符串。
Docker Desktop 本身不提供独立的 YAML 校验界面，所有配置有效性都依赖底层 docker-compose CLI 的解析逻辑。最易被忽略的是：即使 config 通过了，也可能因挂载路径不存在、端口被占、镜像拉取限速等运行时问题卡在 up 阶段——那些得靠日志和系统命令进一步排查。
