YAML 语法详细总结（基于 YAML 1.2 官方规范）

YAML 是 YAML Ain’t Markup Language 的递归缩写，是一种人类优先、可读性极强的数据序列化格式，完全兼容 JSON 语法，广泛用于配置文件、数据交换、自动化编排等场景，主流稳定版本为 YAML 1.2（修复了1.1版本的诸多歧义问题）。

一、核心基础语法规则

这是YAML的语法基石，违反以下规则会直接导致解析失败。

1. 大小写敏感

YAML 对键名、值的大小写严格区分，name 和 Name、port 和 Port 是完全不同的两个键。

Name: Alice  # 键1
name: Bob    # 键2，与上面互不影响

2. 缩进表示层级关系

YAML 完全依靠空格缩进定义数据层级，无大括号、中括号等强制包裹，核心规则：

• 绝对禁止使用 Tab 制表符缩进，必须使用纯空格；
• 缩进空格数不强制（推荐2个空格，云原生场景通用），同一层级的元素必须保持完全一致的缩进；
• 子层级的缩进必须比父层级多至少1个空格。

# 正确示例
person:
  name: Tom
  age: 20
  address:
    city: Shanghai
    street: XX Road

# 错误示例（同级缩进不一致、Tab混用）
person:
name: Tom  # 缩进缺失
  age: 20
    address:  # 缩进层级错误
      city: Beijing

3. 键值对基础格式

YAML 核心结构是 key: value 键值对，强制规则：冒号后面必须跟一个空格，否则会被解析为一个完整的字符串键。

# 正确
app: my-demo
version: 1.0.0

# 错误（冒号后无空格，解析失败）
app:my-demo
version:1.0.0

4. 注释规则

• 仅支持单行注释，使用 # 开头，# 后建议加空格提升可读性；
• 注释可放在行首，也可放在代码行的末尾；
• 无多行注释，多行注释需每行都加 #；
• 单引号/双引号内的 # 会被视为普通字符，不会解析为注释。

# 这是全局注释
app_name: demo-app  # 这是行尾注释
# 多行注释
# 第二行注释
desc: "这是带#号的字符串，不会被注释"

5. 多文档分隔符

一个YAML文件中可包含多个独立的YAML文档，通过分隔符区分：

• ---：表示一个文档的开始，单文档场景可省略，多文档必须用其分隔；
• ...：表示一个文档的结束，非必需，仅用于明确终止文档，多用于网络传输场景。

---
# 第一个文档：开发环境配置
env: dev
port: 8080
...
---
# 第二个文档：生产环境配置
env: prod
port: 80

二、核心数据类型

YAML 数据结构由三种核心类型组成：标量（Scalar）、序列（Sequence）、映射（Mapping），支持无限嵌套组合。

1. 标量类型（单个不可拆分的值）

标量是YAML中最基础的数据单元，对应编程语言中的基础数据类型。

字符串的三种写法与核心区别

字符串是YAML中最易踩坑的类型，三种写法有明确的语义差异：

1. 无引号写法：最简洁，适合纯文本、无特殊字符的字符串，自动识别类型；

   注意：包含 :+空格、#、&、*、{}、[] 等特殊字符时，不能用无引号写法，否则会被解析为语法结构。

   # 正确
   desc: 这是一段普通的无引号字符串
   # 错误（:后有空格，会被解析为键值对）
   error_desc: 错误示例: 包含冒号加空格

2. 单引号写法：强字面量，内部的转义字符（如 \n）不会被解析，仅会把两个连续单引号转义为一个单引号，适合包含特殊字符、但不需要转义的场景。

   # \n 会被当作普通字符，不会换行
   single_quote: '第一行\n第二行，不会换行'
   # 两个单引号转义为一个
   quote_test: '他说：''你好'''

3. 双引号写法：唯一支持转义字符的写法，内部的 \n、\t 等转义符会被正常解析，适合需要换行、特殊符号的复杂字符串。

   # \n 会被解析为换行
   double_quote: "第一行\n第二行，正常换行"
   special_char: "包含双引号\"和转义字符的字符串"

2. 序列类型（数组/列表）

用于表示有序的一组数据，对应编程语言中的数组，支持两种写法：

块式写法（推荐，可读性强）

以 - （短横线+空格）开头，每个元素占一行，同层级元素缩进一致，支持嵌套。

# 基础序列
fruits:
  - Apple
  - Banana
  - Orange

# 嵌套序列（二维数组）
matrix:
  - [1, 2, 3]
  - [4, 5, 6]
  -
    - 7
    - 8
    - 9

流式写法（行内写法）

用方括号 [] 包裹，元素之间用 , （逗号+空格）分隔，适合简短的列表。

# 行内序列
nums: [1, 2, 3, 4, 5]
# 混合嵌套
person:
  name: Jack
  hobbies: [reading, running, coding]

3. 映射类型（字典/对象）

用于表示无序的键值对集合，对应编程语言中的字典/对象，支持两种写法：

块式写法（推荐，可读性强）

每行一个键值对，通过缩进表示嵌套层级，是最常用的写法。

# 基础映射
server:
  host: localhost
  port: 8080
  timeout: 30s

# 嵌套映射
user:
  name: Lucy
  age: 22
  contact:
    email: lucy@example.com
    phone: 138XXXX1234

流式写法（行内写法）

用大括号 {} 包裹，键值对之间用 , （逗号+空格）分隔，适合简短的对象。

# 行内映射
database: { driver: mysql, host: 127.0.0.1, port: 3306 }
# 混合嵌套
app:
  name: demo
  config: { env: dev, debug: true }
  white_list: [127.0.0.1, 192.168.1.1]

三、进阶高级语法

1. 多行字符串处理

YAML 提供了专门的符号处理多行文本，避免大量转义字符，核心分为两种模式：

保留换行符 |（块字面量）

保留文本中所有的换行符和缩进，最终输出的文本会保留多行格式，适合脚本、配置文本、长文案等场景。

# | 保留所有换行，末尾自动加一个换行
script: |
  #!/bin/bash
  echo "Hello YAML"
  cd /opt/app
  npm run start

# |+ 保留末尾所有换行（默认只保留1个，+ 保留全部）
text_plus: |+
  第一行
  第二行

# |- 删除末尾所有换行（默认的末尾换行也会删掉）
text_minus: |-
  第一行
  第二行

折叠换行符 >（块折叠）

将文本中的换行符折叠为一个空格，最终输出为单行文本，仅保留空行对应的换行，适合超长的单行文案、说明文本。

# > 把换行折叠为空格，最终输出为一行
summary: >
  这是一段超长的说明文本，
  我不想在一行里写满，
  用换行拆分，但最终解析后会合并为一行，
  换行符会变成空格。

# 空行会被保留为换行
desc: >