运维 YAML 错误怎么排查

排查运维中 YAML 错误，通常可以按照**“从报错信息 → 语法 → 结构 → 工具 → 上下文”**的系统思路来进行。下面给你一套实战可用的排查方法。

一、先看报错信息（最重要）

大多数 YAML 错误都会给出行号和错误类型：

常见报错示例：

• did not find expected key
• mapping values are not allowed here
• indentation error
• could not find expected ':'

✅ 做法：

• 直接定位报错行
• 看是缩进问题还是语法问题

二、检查最常见的 5 类 YAML 错误

1️⃣ 缩进错误（最高频）

YAML 只用空格，不用 Tab

❌ 错误：

services:
  web:
    image: nginx
      ports:
        - "80:80"

✅ 正确：

services:
  web:
    image: nginx
    ports:
      - "80:80"

✅ 建议：

• 编辑器显示「不可见字符」
• 统一 2 个或 4 个空格

2️⃣ 冒号后面没空格

❌ 错误：

name:app

✅ 正确：

name: app

3️⃣ 特殊字符未加引号

包含 :、#、%、{} 等要加引号

❌ 错误：

command: echo hello: world

✅ 正确：

command: "echo hello: world"

4️⃣ 列表 / 字典混用

❌ 错误：

env:
  - KEY: value

✅ 正确（二选一）：

env:
  KEY: value

或

env:
  - KEY=value

5️⃣ 多文档分隔符错误

多个 YAML 用 --- 分隔：

apiVersion: v1
---
apiVersion: apps/v1

❌ 常见错误：

• 少了 ---
• --- 前后空格不对

三、用工具快速验证（强烈推荐）

✅ 本地校验

yamllint file.yaml

或 Python：

python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.yaml

✅ 在线工具

• https://www.yamllint.com/
• https://yamlvalidator.com/

四、K8s / Docker / Ansible 专项排查

K8s

kubectl apply -f file.yaml --dry-run=client
kubectl explain pod.spec

Docker Compose

docker compose config

Ansible

ansible-playbook playbook.yml --syntax-check

五、上下文排查（容易忽略）

• 是否从网页 / Word 复制产生隐形字符
• 是否混用了 Tab + Space
• 是否文件编码不是 UTF-8
• 是否变量未展开（如 Ansible {{ }}）

六、排查 checklist（可直接用）

• [ ] 是否只用空格
• [ ] 冒号后是否有空格
• [ ] 特殊字符是否加引号
• [ ] 缩进是否对齐
• [ ] 是否通过 yamllint
• [ ] 是否通过对应工具 dry-run

如果你愿意，可以把具体 YAML 文件和报错信息发出来，我可以帮你精确定位并改好。