YAML 语法教程：实用入门指南

YAML（YAML Ain't Markup Language）是一种人类可读的数据序列化格式，广泛用于配置文件、CI/CD 流水线和基础设施即代码。如果你使用 Docker Compose、Kubernetes、GitHub Actions 或 Ansible，那么你每天都在使用 YAML。本教程涵盖了自信编写 YAML 所需的一切。

为什么选择 YAML？

YAML 的主要优势是可读性。对比 JSON 和 YAML 中的相同数据：

JSON：

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML：

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML 用更少的标点符号实现了相同的结构。没有花括号，简单情况下没有方括号，无需强制使用引号。这使得配置文件更易于手动阅读和编辑。

基本数据类型

标量

YAML 自动从值推断类型：

string: hello world          # 字符串（无需引号）
quoted: "hello world"        # 显式字符串
integer: 42                  # 整数
float: 3.14                  # 浮点数
boolean: true                # 布尔值（true/false、yes/no、on/off）
null_value: null             # 空值（也可以用 ~ 或留空）
date: 2025-01-15             # 日期（ISO 8601）

常见陷阱：yes、no、on、off 等值会被解释为布尔值。如果你想要字符串 "yes"，需要加引号："yes"。

字符串和引号

字符串很少需要引号，但某些情况下必须使用：

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

多行字符串

YAML 有两种多行风格：

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

description: |
  This is line one.
  This is line two.
  
  This is line four (after blank line).

折叠块（>） — 用空格连接各行：

description: >
  This is a long paragraph
  that will be folded into
  a single line.

添加 - 可以去除尾部换行符（|-、>-），添加 + 保留它们（|+、>+）。

集合

列表（序列）

# 块风格
fruits:
  - apple
  - banana
  - cherry

# 流式风格（内联）
fruits: [apple, banana, cherry]

映射（键值对）

# 块风格
person:
  name: Alice
  age: 30
  city: London

# 流式风格
person: {name: Alice, age: 30, city: London}

嵌套结构

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

锚点和别名

锚点（&）和别名（*）允许你重用值：

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # 覆盖默认值

<< 合并键将锚点中的所有属性合并进来。在合并之后定义的属性会覆盖锚点中的值。了解更多高级锚点模式，请参阅我们的 YAML 锚点和别名指南。

多文档

单个 YAML 文件可以包含多个文档，用 --- 分隔：

---
# 文档 1：配置
apiVersion: v1
kind: ConfigMap
---
# 文档 2：服务
apiVersion: v1
kind: Service

这在 Kubernetes 清单中很常用。

常见陷阱

1. 缩进错误

YAML 使用空格，绝不使用制表符。不一致的缩进是最常见的错误：

# 错误 - 混合缩进
server:
  host: localhost
    port: 8080  # 错误：意外的缩进

# 正确
server:
  host: localhost
  port: 8080

使用我们的 YAML 格式化工具自动修复缩进问题。

2. 挪威问题

国家代码如 NO（挪威）会被解释为布尔值 false：

# 错误
countries:
  - NO  # 被解释为 false！
  - SE
  - DK

# 正确
countries:
  - "NO"
  - SE
  - DK

3. 未加引号的特殊字符

值中的冒号、井号和方括号需要加引号：

# 错误
message: Error: file not found
url: http://example.com  # 可能会出错

# 正确
message: "Error: file not found"
url: "http://example.com"

4. 版本号陷阱

版本号如 1.0 会被解析为浮点数：

# 错误
version: 1.0  # 变成 1（浮点数）

# 正确
version: "1.0"  # 字符串

验证 YAML

部署前务必验证你的 YAML。YAML 中的语法错误可能导致应用程序出现难以理解的故障。我们的 YAML 验证器可以即时检查语法，精确高亮错误所在的行和列。

要深入了解 YAML 和 JSON 之间的区别，请参阅我们的 YAML vs JSON 对比。

常见问题

YAML 缩进应该使用几个空格？

两个空格是最常见的惯例，被 Kubernetes、Docker Compose、GitHub Actions 和大多数 DevOps 工具采用。某些项目使用四个空格。关键规则是在文件内保持一致——永远不要混合缩进层级。

YAML 支持注释吗？

是的，YAML 支持使用 # 的单行注释。没有多行注释语法。注释在解析时会被去除，在加载的数据结构中不可用。