YAML 语法与验证：常见错误及修复方法

YAML 是 Docker、Kubernetes、CI/CD 流水线和无数其他工具的首选配置格式。尽管语法对人类友好，但 YAML 出错却出奇地容易。本指南涵盖最常见的 YAML 错误及修复方法。

YAML 的使用场景

• Docker Compose (docker-compose.yml)
• Kubernetes 清单文件
• GitHub Actions / GitLab CI 工作流
• Ansible 剧本
• 配置文件（Prettier、ESLint 等）

基本 YAML 语法规则

缩进

YAML 使用空格（不能用制表符）进行缩进。同一层级的空格数必须一致：

# ✅ Correct (2-space indentation)
server:
  host: localhost
  port: 8080
  database:
    name: myapp
    pool: 10

# ❌ Wrong (tab characters or inconsistent spaces)
server:
	host: localhost    # Tab character - INVALID!
   port: 8080        # 3 spaces - inconsistent!

键值对

键和值之间用冒号加空格分隔：

# ✅ Correct
name: John Doe
port: 8080

# ❌ Wrong - missing space after colon
name:John Doe

多行字符串

YAML 提供两种块标量样式来处理多行字符串：

# | (literal block) - preserves newlines
description: |
  This is line one.
  This is line two.
  Each newline is preserved.

# > (folded block) - folds newlines to spaces
description: >
  This is a long paragraph
  that will be joined into
  a single line.

YAML 数据类型

"挪威问题"

在 YAML 1.1 中，`NO`（如挪威的国家代码）会被解释为布尔值 `false`。因为 YAML 1.1 将 yes/no、on/off、true/false 视为布尔值。务必给国家代码等类似值加引号：

# ❌ YAML 1.1 interprets these as booleans!
country: NO        # → false
answer: yes        # → true
switch: on         # → true

# ✅ Fix: quote the values
country: "NO"      # → string "NO"
answer: "yes"      # → string "yes"
switch: "on"       # → string "on"

集合：列表和映射

# List (sequence)
fruits:
  - apple
  - banana
  - cherry

# Nested map
database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret

# Inline / Flow style
fruits: [apple, banana, cherry]
point: {x: 10, y: 20}

十大常见 YAML 错误

YAML vs JSON vs TOML

验证最佳实践

• 始终在 CI/CD 流水线中使用 YAML 校验器
• 配置编辑器显示空白字符
• 使用 2 空格缩进（最常见约定）
• 给可能被误解的字符串加引号（布尔值、前导零的数字）
• 对复杂配置使用 YAML 模式验证
• 尽可能保持 YAML 文件小而模块化

常见问题