YAML格式介绍

日期：2025-10-26

YAML 以其简洁和可读性著称，但正因为其简洁，一些语法规则非常严格，容易出错。以下是一些常见的 YAML 语法错误点和需要注意的事项：

核心原则与高频错误点

缩进是关键 (Indentation Matters)
- 规则： YAML 使用空格（强烈推荐只使用空格）进行缩进来表示结构层次（如映射、序列的嵌套）。制表符 (Tab) 不被允许用于缩进！ 混合使用空格和制表符是常见错误源。
- 错误点：
  - 使用制表符代替空格。
  - 同一层级缩进使用的空格数不一致（例如，一个地方用 2 个空格，另一个地方用 3 个或 4 个空格）。
  - 嵌套层级缩进错误（例如，子项没有比父项多缩进）。
- 建议： 在编辑器中设置将 Tab 键转换为空格（例如，设置为 2 个或 4 个空格），并始终保持缩进一致。
键值对分隔符 (Key-Value Separator)
- 规则： 映射（键值对）中的键和值之间必须有一个冒号 :，并且冒号后面必须紧跟一个空格。
- 错误点：
  - 忘记写冒号 :。
  - 冒号 :后面没有加空格（key:value是错误的，必须是 key: value）。
  - 错误地使用了等号 =或其他符号。
- 示例：
```
# 正确
name: John Doe
age: 30

# 错误 (缺少空格)
name:John Doe

# 错误 (使用了等号)
name = John Doe
```
字符串引号 (String Quoting)
- 规则： 字符串通常不需要引号，除非：
  - 字符串包含特殊字符（如 :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, ``）。
  - 字符串看起来像其他数据类型（如数字 123，布尔值 true/false/yes/no，null），但你希望它被解释为字符串。
  - 字符串包含换行符（需要使用块标量样式 |或 >）。
  - 字符串开头或结尾有空格。
- 错误点：
  - 在不需要引号的地方使用了引号（虽然语法允许，但不必要）。
  - 在需要引号的地方忘记使用引号，导致解析错误或值类型错误（例如，version: 1.10是数字，version: "1.10"是字符串；on: yes可能被解析为布尔值 true，而 on: "yes"是字符串）。
  - 引号使用不一致（单引号 'vs 双引号 "）。单引号内不转义特殊字符（\n就是字面的 \n），双引号内可以转义（\n是换行符）。
- 建议： 当字符串包含可能引起歧义的字符或看起来像其他类型时，使用双引号。对于多行字符串，使用块标量（|或 >）。
序列/列表 (Sequences/Lists)
- 规则： 使用短横线加空格 -表示列表项。每个列表项必须缩进相同的层级。
- 错误点：
  - 忘记短横线 -后面的空格（-item是错误的，必须是 - item）。
  - 列表项缩进不一致。
  - 试图在同一行写多个列表项而没有正确的分隔（行内序列需要用方括号 []）。
- 示例：
```
# 正确 (块样式)
fruits:
  - Apple
  - Banana
  - Orange

# 正确 (行内样式)
fruits: [Apple, Banana, Orange]

# 错误 (缺少空格)
fruits:
  -Apple

# 错误 (缩进不一致)
fruits:
  - Apple
    - Banana # 这个 - 应该和上面的 - 对齐
```
映射/字典 (Mappings/Dictionaries)
- 规则： 键值对是基础。嵌套映射通过缩进表示。
- 错误点：
  - 嵌套映射的缩进错误。
  - 重复键（同一个映射内不能有两个相同的键）。
- 示例：
```
# 正确
person:
  name: Alice
  address:
    street: 123 Main St
    city: Anytown

# 错误 (重复键)
person:
  name: Alice
  name: Bob # 错误！同一个映射中不能有两个 'name' 键
```
多行字符串/块标量 (Multiline Strings / Block Scalars)
- 规则： 使用 |（保留换行符和末尾空白）或 >（折叠换行符为空格，但保留空行和行尾空白）后跟一个块样式指示符（可选，如 |+, |-, >+, >-控制末尾换行）和换行符，然后缩进书写多行内容。
- 错误点：
  - 忘记 |或 >后面的换行符。
  - 多行内容的缩进不正确（内容必须比块标量指示符多缩进至少一级）。
  - 混淆 |和 >的行为。
- 示例：
```
# 正确 (| 保留换行)
description: |
  This is a long description
  that spans multiple lines.
  Each line break is preserved.

# 正确 (> 折叠换行)
folded: >
  This is a folded string.
  Newlines become spaces,
  but blank lines are preserved.

# 错误 (缺少内容缩进)
wrong: |
This line is not indented more than the block indicator. # 错误！这行必须缩进
```
注释 (Comments)
- 规则： 使用井号 #表示注释。#必须出现在一行的开头，或者出现在空格之后。注释持续到行尾。
- 错误点：
  - 试图在字符串内使用 #作为注释（字符串内的 #就是字符）。
  - 在键或特殊字符前误用 #。
- 示例：
```
# 这是一个注释
key: value # 这也是一个注释
# 错误：下面的 # 是字符串的一部分
string: This is a # not a comment
```
数据类型识别 (Data Type Detection)
- 规则： YAML 会自动推断标量的类型（字符串、布尔值、整数、浮点数、空值等）。
- 错误点：
  - 期望是字符串的值被解析为其他类型（如 yes, no, true, false, on, off, null, 数字等）。如果不希望自动转换，请加引号。
  - 格式不正确的数字或布尔值。
- 示例：
```
# 被解析为布尔值 true
enabled: yes

# 被解析为字符串 "yes"
enabled: "yes"

# 被解析为整数 123
port: 123

# 被解析为字符串 "123"
port: "123"

# 错误 (无效的布尔值)
flag: maybe # 可能被解析为字符串 "maybe"，如果期望是布尔值则逻辑错误
```
锚点与别名 (Anchors & Aliases)
- 规则： 使用 &定义锚点，使用 *引用别名，用于避免重复。
- 错误点：
  - 锚点名称定义或引用错误（拼写不一致）。
  - 在不能使用别名的地方使用（例如，在键中）。
  - 循环引用。
- 示例：
```
# 正确
defaults: &defaults
  adapter: postgres
  host: localhost

development:
  <<: *defaults # 合并 default 的键值对
  database: dev

# 错误 (别名名称错误)
production:
  <<: *default # 应该是 *defaults
```
文档开始与结束 (Document Start and End)
- 规则： 单个 YAML 文件可以包含多个文档，用 ---（文档开始）和 ...（文档结束，可选）分隔。
- 错误点：
  - 在不需要多个文档时误用了 ---（这可能导致解析器期望后续内容）。
  - 混淆 ---和注释或其他符号。