YAML 排坑实战：类型推断、缩进与多行字符串的静默炸弹

类型推断：YAML 最大的静默炸弹

YAML 会自动推断标量类型，很多「看起来是字符串」的值会被静默转换：no/na/n 变布尔 false（著名的挪威问题），on/off/yes 变 true/false，0733 变八进制，1.10 变数字 1.1。

后果是配置「看着对、跑起来错」：版本号丢失精度、国家代码变布尔。除非明确要数字/布尔/null，标量一律加引号——这是 YAML 最省心的一条纪律。

country: no          # 实际是 false，不是挪威！
country: "no"       # 这才是字符串
version: 1.10       # 变成数字 1.1
version: "1.10"    # 字符串，安全

什么时候必须加引号

三类值必须引号：① 可能被推断为数字/布尔/null 的（no、on、1.10，以及会被解析成日期对象的 2026-01-01）；② 以特殊字符开头的（* & ! % @）；③ 值里含「冒号+空格」或 # 的。

日期坑单独强调：date: 2026-01-01 在多数解析器里是日期对象而非字符串，日志排查时会以完全不同的形态出现。写 date: "2026-01-01" 才是字符串。

date: 2026-01-01      # 日期对象，不是字符串
date: "2026-01-01"   # 字符串
value: a: b           # 语法错误（冒号+空格）
value: "a: b"        # 正确

缩进与结构：错一层，数据落到别的节点

YAML 只认空格不认 Tab（Tab 直接语法错误）；同级键必须对齐；列表项 - 后的内容属于子层级。结构错一层，数据就静默落到别的节点下——多数解析器根本不报错。

两个高频细节：冒号后必须有空格（key:value 是错的）；注释 # 前要有空格，否则被当作值的一部分。编辑器装 YAML 语言服务（如 VSCode 的 Red Hat YAML）能实时标出这类错误。

server:
  host: 0.0.0.0     # 缩进 2 空格，属于 server
  ports:
    - 80            # 列表项再缩进一级
    - 443
# key:value 错 → key: value 对

多行字符串：| 与 > 的区别

竖线 | 保留换行（字面块），折角 > 把换行折叠成空格（折叠块），加 - 表示去掉末尾换行（|-、>-）。写脚本、证书、SQL 这类内容时用 |；写长段落说明时用 >。

块的缩进基准取第一行：块内所有行必须比父键多缩进且一致——这就是「明明对齐了还报错」的原因：和上一层比错了对象。

script: |
  #!/usr/bin/env bash
  set -euo pipefail
  echo "ok"
desc: >
  这是一段很长的说明文字，
  换行会被折叠成空格。
sql: |-
  SELECT *
  FROM users;

锚点、别名与合并：复用公共片段

锚点 &name 打标记，别名 *name 引用它，<<: 把一个映射合并进当前键——docker-compose 复用公共配置就靠这套机制。

两个限制要知道：数组（列表）不能用 << 合并，只能整体引用；别名是「引用」不是「拷贝」，改一处全变。顺带一个高频暗雷：端口映射 80:80 不加引号在 YAML 1.1 里会被解析成 60 进制数字，compose 里务必写成字符串 "80:80"。

common: &common
  image: nginx:1.27
  restart: unless-stopped
web:
  <<: *common
  ports:
    - "80:80"

排错工具链与收尾清单

上线前用工具验证：yamllint 查风格与结构；用目标工具本身解析一遍（docker compose config、kubectl --dry-run）；Python 侧一条 yaml.safe_load 即可快速确认解析结果是否符合预期。

排查原则：报错行号往往指向「问题显现处」，真正的错常在上方几行的缩进或引号。清单：标量加引号、缩进只用空格、冒号后空格、多行块选对 |/>、端口映射写引号、提交前过一遍解析器。

yamllint config.yaml
docker compose config        # 解析并规范化输出
kubectl apply --dry-run=client -f manifest.yaml
python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" config.yaml