YAML 基础

本文记录 YAML 格式文件的常见写法 ¹ ²。

YAML (Yet Another Markup Language) 主要用于配置文件，比如：Kubernetes、Docker Compose 和 GitHub Actions 等。后缀名为 .yml 或 .yaml。格式规范和 Python 类似，都是用空格与换行区分不同的逻辑块，但是不能用 tab，至于几个空格无所谓，只要前后文一致即可。

注释

# 这是注释
server:
    port: 8080
    host: localhost

字典

使用 key: value 形式，: 后面必须有一个空格：

name: John Doe
age: 30
is_student: false

也可以嵌套使用字典：

person:
    name: Alice
    age: 25
    address:
        city: New York
        zip: 10001

等价于：

{
    "person": {
        "name": "Alice",
        "age": 25,
        "address": {
            "city": "New York",
            "zip": 10001
        }
    }
}

列表

使用 - 表示一个列表项，必须缩进对齐：

fruits:
    - apple
    - banana
    - cherry

等价于：

{
    "fruits": ["apple", "banana", "cherry"]
}

列表嵌套字典

users:
    - name: Alice
      age: 25
    - name: Bob
      age: 30

等价于：

{
    "users": [
        { "name": "Alice", "age": 25 },
        { "name": "Bob", "age": 30 }
    ]
}

字典嵌套列表

department:
    name: Engineering
    employees:
        - Alice
        - Bob
        - Charlie

等价于：

{
    "department": {
        "name": "Engineering",
        "employees": ["Alice", "Bob", "Charlie"]
    }
}

多行字符串

使用 | 表示保持换行：

msg: |
    This is a multiline string.
    Each line is preserved as-is.

等价于：

{
    "msg": "This is a multiline string.\nEach line is preserved as-is.\n"
}

使用 > 表示将换行转换为空格：

msg: >
    This is a long message
    that will be collapsed into
    a single line.

等价于：

{
    "msg": "This is a long message that will be collapsed into a single line."
}

复用配置

使用 & 符号定义当前配置项的别名，用于后续复用：

defaults: &default_settings
    timeout: 30
    retries: 5

使用 * 符号表示复用对应的配置，使用 << 表示合并到对应的配置：

server1:
    <<: *default_settings
    host: server1.com

server2:
    <<: *default_settings
    host: server2.com

等价于：

YAMLJSON

defaults: &default_settings
    timeout: 30
    retries: 5

server1:
    timeout: 30
    retries: 5
    host: server1.com

server2:
    timeout: 30
    retries: 5
    host: server2.com

{
    "defaults": {
        "timeout": 30,
        "retries": 5
    },
    "server1": {
        "timeout": 30,
        "retries": 5,
        "host": "server1.com"
    },
    "server2": {
        "timeout": 30,
        "retries": 5,
        "host": "server2.com"
    }
}