如果本站关于 YAML 的文章你只打算读一篇，就读这篇。这个格式看着温顺，藏着比它那张笑脸多得多的边界情况。下面是我反复回看的语法参考，每条规则都配一段能直接跑的例子。
缩进：只用空格，而且要一致
YAML 用缩进表达层级，而且只接受空格，绝不接受 Tab。缩进几格随你，但每一层必须一样。
server:
host: localhost
port: 8080
limits:
cpu: "2"
memory: 4G社区惯例是每层两个空格。选了就稳住；少缩进两格是"YAML 合法、结构却错了"最常见的原因。
标量，以及什么时候该加引号
标量就是任意单个值。不加引号的标量写起来爽，但解析器会猜它的类型。只要值不是干净的数字或一眼能看出的布尔，就加引号：
password: "1234abc" # 加引号：以数字开头
version: "1.10" # 加引号：保住字符串，别变成 1.1
active: yes # 1.1 会把它解析成布尔 true
path: "C:\temp" # 加引号：反斜杠和冒号都有风险
token: "true" # 加引号：你要的是字符串，不是布尔双引号支持转义（\n、\t）；单引号几乎一切照字面处理，只有两个单引号连写才表示一个单引号。当值里含有 :、#、{、}、[、]、,，或以特殊符号开头时，请加引号。
块标量与 chomping 标志
多行文本有两种块样式，外加一个控制行尾换行的 chomping 标志。
|—— 字面块：每个换行都保留。>—— 折叠块：换行变成空格，适合写段落。
chomping 标志写在符号后面：
| 写法 | 名称 | 行尾换行的行为 |
|---|---|---|
| / > | clip（默认） | 保留恰好一个行尾换行 |
|- / >- | strip | 去掉所有行尾换行 |
|+ / >+ | keep | 保留所有行尾换行 |
三种 chomping 放在一起对比：
clip: |
one
two
strip: >-
one
two
keep: >+
one
two
仔细看。clip 以一个换行结尾；strip 一个换行都没有；keep 保留了 "two" 之后那两个空行。这正是大多数教程跳过的细节，也正是你把 heredoc 或证书粘回去时出问题的地方。
流式写法：像 JSON 一样的单行
结构小的时候，可以写在一行里（流式写法）：
person: { name: devtul, roles: [admin, dev] }
matrix:
- { a: 1, b: 2 }
- { a: 3, b: 4 }流式写法在任何地方都是合法 YAML，这也是为什么把 JSON 粘进 YAML 仍然能解析。紧凑的值用流式，人要读的内容用块式。
锚点与别名：定义一次，复用多处
用锚点（&name）定义一段，再用别名（*name）引用：
defaults: &base
adapter: postgres
pool: 5
production:
<<: *base
database: prod
pool: 20别名 *base 把整个 defaults 映射拉进来。合并键 << 是个特殊键，意思是"把那个锚定的映射合并进当前这个" —— 这里 adapter 和 pool 被继承，随后 pool 被覆盖成 20。锚点能砍掉大配置里的重复，但也会掩盖值的来源，所以只在重复真的存在时才用。
一个文件里多份文档
单个 .yml 文件可以装多份文档，用 --- 分隔，可选地用 ... 收尾：
---
name: first
value: 1
---
name: second
value: 2
...Kubernetes 就是这样读一个目录下的 manifest 的，有些 CI 也这样堆叠 job。不是所有解析器都暴露多文档，但这是 YAML 的核心语法。
显式类型标签
推断不够用时，可以用标签强制类型：
code: !!str 1234 # 永远是字符串 "1234"
ratio: !!float 1 # 数字 1.0
missing: !!null nil # 显式空值标签以 !! 开头表示标准 schema。当加了引号解析器还在猜时，标签是最后的退路。
注释
一行里 # 之后的内容都是注释，会被从数据中剔除：
port: 8080 # 仅本地开发
# debug: true # 整行被注释掉注释，就是 YAML 在配置文件之战里打败 JSON 的原因。用它记下"为什么"这个值长这样；六个月后，那段背景比值本身更值钱。
写完就验证
上面这些，要是一条笔误悄悄改了你的数据结构，就全白搭。写完文件，打开 YAML 查看器 检查一下解析出来的树 —— 尤其是块标量和锚点是否如你所愿。