YAML 语法速查表 - YAML 配置语法常用命令大全
写 Docker Compose、Kubernetes、GitHub Actions 的配置时，缩进错了、冒号后漏空格、特殊字符忘加引号是最常见的错误来源。这份速查把 8 组最常用写法——基础语法、数据类型、列表与字典、多行字符串、锚点引用、类型转换——按用途排好：写新配置时对照结构，报错时按节排查缩进与引号；同时标注了 YAML 与 JSON 的差异（单引号不转义、可加注释、支持锚点复用）。读完你就能独立写出结构清晰、可维护的配置文件。
典型使用场景
写 Docker Compose、Kubernetes、GitHub Actions 或任何 YAML 配置的人，最常遇到两类场景：从零搭一份能运行的配置，或配置报错时定位语法问题。比如为服务写 compose 文件，端口值 "8080:80" 必须用双引号包住，否则会被解析成序列；多个服务要复用公共字段时，用锚点 defaults 定义一次，再通过 << 合并进各服务，避免重复复制整块配置。读完并对照本表，你能独立写出结构正确的 YAML，并在报错时快速判断是缩进、冒号空格还是引号缺失的问题。
基础语法 Basic Syntax 8
key: value键值对（冒号后必须有空格）
# 注释单行注释
---文档分隔符（多文档用）
...文档结束符
string字符串（默认不需要引号）
"string" / 'string'双引号（支持转义）/ 单引号（不转义）
key: "value: with colon"值含特殊字符（: # 等）需加引号
key with spaces: value键名可含空格（无需引号）
数据类型 Data Types 8
null / ~空值（显式声明键无值，避免读取时报类型错误）
true / false布尔值（true 真 false 假，常用来作为功能开关）
123 / 0x1A / 0o17 / 0b1010整数（十进制/十六/八/二进制）
3.14 / .inf / -.inf / .nan浮点数（无穷大/NaN）
2026-07-19日期（ISO 8601）
2026-07-19T10:30:00Z日期时间（UTC）
2026-07-19T10:30:00+08:00带时区的日期时间
!!binary "aGVsbG8="二进制数据（base64 编码）
列表 List / Array 6
- item1\n- item2块风格列表
[item1, item2]流风格列表（行内）
fruits:\n - apple\n - banana嵌套列表
items: []空列表
matrix:\n - [1, 2]\n - [3, 4]列表中的列表
users:\n -\n name: tom\n age: 20列表中放字典
字典 Dictionary / Object 6
key1: value1\nkey2: value2块风格字典
{key1: value1, key2: value2}流风格字典（行内）
person:\n name: tom\n age: 20嵌套字典
person: {name: tom, age: 20}流风格嵌套字典
config: {}空字典
server:\n host: localhost\n ports:\n - 80\n - 443字典与列表混合嵌套
多行字符串 Multiline String 7
text: |\n line1\n line2保留换行（Literal 标量）
text: >\n line1\n line2折叠换行为空格（Folded 标量）
text: "line1\nline2"双引号内显式换行
text: |-\n line1\n line2保留换行并去除末尾换行（- chomp）
text: |+\n line1\n line2保留换行并保留末尾空行（+ chomp）
text: |2\n line1\n line2指定缩进指示数字（2 个空格）
text: >-\n line1\n line2折叠换行并去除末尾换行
锚点与引用 Anchor & Alias 6
default: &default\n key: value定义锚点（&）
env: *default引用锚点（*）
env:\n <<: *default\n extra: value合并锚点到当前字典（<<）
list: &list [a, b, c]为列表定义锚点
copy: *list引用列表锚点
config:\n <<: [*base, *override]合并多个锚点（后者覆盖前者）
类型强制转换 Type Conversion 8
key: !!str 123将整数转为字符串 "123"
key: !!int "42"将字符串转为整数 42
key: !!float "3.14"将字符串转为浮点数
key: !!bool "yes"将字符串转为布尔值
key: !!timestamp "2026-07-19"将字符串转为时间戳
key: !!null ""将空字符串转为 null
key: !!seq {}显式声明为序列类型
key: !!map []显式声明为映射类型
实用示例 Real-world Examples 5
services:\n web:\n image: nginx:latest\n ports:\n - "80:80"Docker Compose 服务定义
steps:\n - name: Checkout\n uses: actions/checkout@v4GitHub Actions 步骤
apiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: my-appKubernetes 资源定义
---\ntitle: My Post\ndate: 2026-07-19\n---Front Matter（文章元信息）
env:\n DATABASE_URL: postgres://localhost/mydb环境变量配置
命令示例
用锚点合并复用公共配置
defaults: &defaults\n replicas: 2\n image: nginx:1.25\n env: production\n\napp:\n <<: *defaults\n name: web&defaults 定义锚点，<<: *defaults 把公共字段合并进 app；显式写的 name: web 覆盖同名锚点键。多服务复用公共配置时可避免逐段复制。
输出
解析后等价于：\napp:\n name: web\n replicas: 2\n image: nginx:1.25\n env: production
Docker Compose 端口映射要加引号
services:\n web:\n image: nginx:latest\n ports:\n - "8080:80"\n environment:\n NGINX_PORT: "80"ports 里的 "8080:80" 必须加双引号，否则冒号加数字会被解析成序列语法而报错；environment 中的值想保留字符串语义时同样建议加引号。
常见坑与注意事项
- 缩进必须一致：同一层级不混用空格数量、更不能使用 Tab，否则解析器报错或产生意外的深层嵌套。
- 冒号后必须有空格（key: value），否则整行被当字符串处理，配置静默不生效。
- 值以 : # @ 等特殊字符开头时需加引号，避免被当成标签、注释或锚点语法。
- 日期与数字会被自动类型推断（2026-07-19 会解析成 Date），需要字符串语义时主动加引号。
- << 合并键的优先级低于显式键：同名键以显式定义为准，不要指望锚点能覆盖已写的值。
提示
- YAML 对缩进敏感，必须用空格不能用 Tab，同一层级必须对齐。
- 冒号后必须有空格（key: value），否则会被解析为字符串。
- 多行字符串用 | 保留换行，用 > 折叠换行（适合长段落）。
- 字符串含特殊字符（: # @ ` 等）时需加引号，避免解析歧义。
- 锚点 & 定义、别名 * 引用、<< 合并键可减少重复配置。
- 多文档用 --- 分隔，常见于 Front Matter 和 CI/CD 配置。
由 巧匠 维护
公开更新于 2026年7月21日，内容持续校对官方文档。