入门：定位、缩进骨架与三类节点
基于 YAML 1.2.2 · 核于 2026-07
速查
- 定位：YAML 是对人类友好的数据序列化语言（不是编程/标记语言），首要目标是易读；配置文件首选，广泛用于 k8s、Docker Compose、GitHub Actions、Ansible。
- 全称：YAML Ain't Markup Language（递归缩写，强调面向数据而非标记）；文件扩展名
.yaml或.yml（等价，官方推荐.yaml）。 - 三类节点：标量 scalar（字符串/数字/布尔/null）、序列 sequence（列表）、映射 mapping（键值对）。
- 缩进即层级：靠前导空格数表达嵌套；规范禁止用 Tab 缩进（不同系统 Tab 宽度不一致），只能用空格；同层键必须对齐到相同缩进列。
- 映射：
key: value，冒号后必须有一个空格；key:value（无空格）会被当成一整个字符串标量。 - 序列：每个元素
- item（短横线后有空格）；同缩进层的多个-构成一个列表。 - 流式写法（借自 JSON）：序列
[1, 2, 3]、映射{name: Alice, age: 30}，适合短小内容写一行。 - 标量类型：
true/false→ 布尔（core schema 仅认这两种）；42/3.14→ 数字；~/null/键后留空 → null；其余默认字符串。 - 引号：普通标量最简洁；含
:#[{等特殊字符或形似其他类型时要加引号。单引号按字面（仅''转义一个单引号），双引号支持\n\t\uXXXX转义。 - 注释：
#起，到行尾；行内注释#前需空白；注释不能出现在标量内部，解析后丢弃。 - 多文档：一个流可含多个文档，用
---分隔文档起始，...标记文档结束（可选）。 - 与 JSON：JSON 几乎是 YAML 1.2 的子集，合法 JSON 基本能被 YAML 解析；YAML 额外有注释/锚点/多行块等能力。
- ⚠️ 隐式类型坑：
no/yes/on/off、1.20、010、邮编前导零可能被误转类型——形似其他类型的字符串务必加引号。 - 进阶顺序：本页 → 标量与字符串 → 集合与文档结构 → 锚点、别名与合并键 → 类型、Schema 与坑 → 参考。
一、YAML 是什么：定位与选型
YAML 官方定义是「一种对人类友好、跨语言、基于 Unicode 的数据序列化语言」，围绕动态语言的常见原生数据类型设计。它只描述数据（映射、序列、标量三类结构），不带循环/条件等编程能力，也不是给文档做标记的标记语言——名字「YAML Ain't Markup Language」本身就在澄清这一点。它的首要设计目标是易于人类阅读，因此成了写配置的首选。
放进「配置格式」里横向对比，选型口径大致是：
| 维度 | YAML | JSON | TOML |
|---|---|---|---|
| 首要定位 | 人类友好的配置/序列化 | 机器友好的数据交换 | 清晰直观的应用配置 |
| 注释 | ✅ # | ❌ 无 | ✅ # |
| 可读性 | 高（缩进无括号噪音） | 中（括号/引号多） | 高（扁平 key = value） |
| 复用能力 | ✅ 锚点/别名/合并键 | ❌ 无 | ❌ 无 |
| 多行文本 | ✅ | / > 块标量 | ❌ 只能 \n 转义 | ✅ 三引号 |
| 隐式类型坑 | 多（Norway 等） | 少（类型显式） | 少（类型明确） |
| 典型场景 | k8s / CI/CD / Ansible | API / package.json | Cargo / pyproject |
一句话选型：要机器间传数据、要严格无歧义 → JSON；要人写复杂配置、需要注释/复用/多行 → YAML；中小型应用配置、想要类型清晰又不易踩坑 → TOML。完整对比见参考页。
二、基础骨架：缩进、映射与序列
YAML 用缩进（前导空格数）表达层级，这是它区别于 JSON 大括号的核心。三条铁律：
- 只能用空格缩进，禁止 Tab——不同系统对 Tab 的显示宽度不一致，会破坏可移植性；
- 同一层级的键必须对齐到相同的缩进列；
- 缩进用几个空格由你定（惯例 2 个），但全文件要一致。
# 映射（键值对）：冒号后必须有空格
name: Alice
age: 30
# 嵌套映射：子键比父键缩进更深
server:
host: localhost
port: 8080
# 序列（列表）：每个元素以 - 开头
fruits:
- apple
- banana
- cherry
# 序列的元素是映射（k8s/CI 里最常见的结构）
users:
- name: Alice
role: admin
- name: Bob
role: guest冒号后的空格是硬性要求
key: value 里冒号后的那个空格不能省。写成 key:value 时，YAML 会把整行当成一个字符串标量 key:value，而不是键值对——这是最高频的初学者坑，写 URL（http://...）或时间（12:30）时尤其容易触发，遇到就给整个值加引号。
三、流式写法：借自 JSON
除了上面的块式（block，靠缩进换行）写法，YAML 还支持流式（flow，用括号写一行）写法，语法与 JSON 一致，适合短小内容：
# 流式序列（等价于块式的多行 - 列表）
fruits: [apple, banana, cherry]
# 流式映射（等价于块式的缩进键值对）
point: { x: 10, y: 20 }
# 因为 JSON 是 YAML 1.2 的子集，这段合法 JSON 也是合法 YAML
config: { "name": "Alice", "tags": ["a", "b"], "enabled": true }块式与流式语义等价，只是排版风格不同——长列表/深嵌套用块式更易读，短小内容用流式更紧凑。
四、标量：字符串、数字、布尔与 null
标量是最小的数据单元。YAML 会按 core schema 的规则对不加引号的标量做类型推断：
a_string: hello world # 普通标量 → 字符串
a_number: 42 # → 整数 int
a_float: 3.14 # → 浮点 float
a_bool: true # → 布尔（core schema 只认 true/false）
a_null: ~ # → null（也可写 null，或键后留空）
quoted_num: "42" # 加引号 → 字符串 "42"，不再是数字引号的选择很关键：
- 普通标量（不加引号）最简洁，但值里含
:#[{&*等特殊字符，或形似布尔/数字/null 时，需要加引号避免被误解析； - 单引号几乎不转义，内容按字面保留，唯一转义是用两个连续单引号
''表示一个字面单引号； - 双引号支持完整转义序列（
\n换行、\t制表、\"引号、\uXXXXUnicode），需要这些转义时必须用双引号。
形似其他类型的字符串，一律加引号
邮编 010010、电话、版本号 1.20、国家代码 NO、纯数字 ID 等「看着像别的类型、实则是字符串」的值，都应加引号锁定为字符串，否则会被隐式转成数字/布尔而损坏数据。类型推断与坑详见类型、Schema 与坑。
五、注释与多文档
# 这是一整行注释
name: Alice # 这是行内注释，# 前要有空白分隔
--- # 三个短横线：一个文档的开始（分隔多文档）
kind: Service
---
kind: Deployment
... # 三个点：文档结束（可选，通信管道常用）- 注释
#：从井号到行尾都是注释；行内注释的#前必须有空白；注释不能出现在标量内部（否则被当字符串字符）；注释是表现层细节，解析后丢弃。 - 多文档：一个 YAML 流（文件）可以包含多个文档，用
---分隔——Kubernetes 把多个资源对象写进一个文件就靠它；...表示文档结束但不开启新文档。
打好地基后，下一步进入 标量与字符串：三种引号的取舍、字面块 | 与折叠块 > 多行文本、chomping 削减指示符，以及显式类型标签。