YAML 语法速查表 - YAML 配置语法常用命令大全

Q: 为什么 key: value 少写一个空格就被解析成字符串？

YAML 规定冒号后必须跟一个空格才算键值分隔。写成 url:localhost:3306 时，整行会被当作一个普通标量字符串，读取 map 时就拿不到 key。正确写法是 url: localhost:3306；如果值本身带冒号又不想被误读，用双引号包起来 key: "value: with colon"。同理 Tab 不能用于缩进，必须用空格且同层对齐。

Q: 多行文本该用竖线 | 还是大于号 >？

看你要不要保留原文换行。text: | 是 Literal 标量，逐行原样保留换行，适合代码块、配置片段；text: > 是 Folded 标量，把连续换行折叠成一个空格，适合长段落说明。两者都可加 chomp 修饰符：|2 指定缩进指示数字，|- 保留换行但去掉末尾换行，>- 折叠并去尾换行。需要精确控制时用双引号写 text: "line1\nline2"。

Q: 锚点 &、别名 * 和合并键 << 什么时候值得用？

同一份默认值要在一堆地方重复时用它。先用 default: &default 定义锚点，别处写 env: *default 引用；想把锚点当基底再叠加局部覆盖，用合并键 env:\n <<: *default\n extra: value。多个锚点还能一次合并：config:\n <<: [*base, *override]，后者覆盖前者。列表同样可以锚定：list: &list [a, b, c] 之后 copy: *list。

Q: 配置里的数字和布尔被读成字符串，怎么强制类型？

在值前面加显式标签即可：key: !!str 123 把整数 123 变字符串，reverse 方向同样成立。常用标签还有 !!int "42" 字符串转整数、!!float "3.14" 转浮点、!!bool "yes" 转布尔、!!timestamp "2026-07-19" 转时间戳、!!null "" 把空串转成 null。也可以用 !!seq {} / !!map [] 显式声明序列或映射类型，避免下游把它当字符串。

Q: 一个文件里写了好几份配置，--- 分隔符该怎么用？

--- 是文档分隔符，把一个文件切成多个独立文档，每个文档有自己的顶层结构，解析器一次可拿到文档列表。典型场景是 Front Matter：文件开头先写 ---，里面放 title: My Post 和 date: 2026-07-19，再用 --- 收尾，正文当作第二份文档。... 标记文档显式结束。多文档常出现在 CI/CD 与 Kubernetes 配置里，每个 --- 之后是一份独立资源定义。

写 Docker Compose、Kubernetes、GitHub Actions 的配置时，缩进错了、冒号后漏空格、特殊字符忘加引号是最常见的错误来源。这份速查把 8 组最常用写法——基础语法、数据类型、列表与字典、多行字符串、锚点引用、类型转换——按用途排好：写新配置时对照结构，报错时按节排查缩进与引号；同时标注了 YAML 与 JSON 的差异（单引号不转义、可加注释、支持锚点复用）。读完你就能独立写出结构清晰、可维护的配置文件。

配置格式·共 54 条命令·最后更新 2026-07-21

典型使用场景

面向需要手写或维护配置文件的开发者：Docker Compose、Kubernetes 清单、GitHub Actions 工作流、CI/CD 流水线、前端构建工具配置。本表把最容易踩坑的几处一次讲透——冒号后必须留空格否则被当成字符串、缩进只能用空格不能用 Tab、多行字符串的 | 与 > 如何选择 chomp 行为、以及锚点 & 与合并键 << 如何消除重复配置。锚点合并尤其适合 Compose 文件里多个服务共享同一套 environment、CI 里多个 job 复用同一份环境变量，改一处即可全量生效。类型强制转换 !!str / !!int 一节则用来解决「环境变量全是字符串」这个经典痛点。

基础语法 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
- item2

块风格列表

[item1, item2]

流风格列表（行内）

fruits:
  - apple
  - banana

嵌套列表

items: []

空列表

matrix:
  - [1, 2]
  - [3, 4]

列表中的列表

users:
  -
    name: tom
    age: 20

列表中放字典

字典 Dictionary / Object 6

key1: value1
key2: value2

块风格字典

{key1: value1, key2: value2}

流风格字典（行内）

person:
  name: tom
  age: 20

嵌套字典

person: {name: tom, age: 20}

流风格嵌套字典

config: {}

空字典

server:
  host: localhost
  ports:
    - 80
    - 443

字典与列表混合嵌套

多行字符串 Multiline String 7

text: |
  line1
  line2

保留换行（Literal 标量）

text: >
  line1
  line2

折叠换行为空格（Folded 标量）

text: "line1\nline2"

双引号内显式换行

text: |-
  line1
  line2

保留换行并去除末尾换行（- chomp）

text: |+
  line1
  line2

保留换行并保留末尾空行（+ chomp）

text: |2
  line1
  line2

指定缩进指示数字（2 个空格）

text: >-
  line1
  line2

折叠换行并去除末尾换行

锚点与引用 Anchor & Alias 6

default: &default
  key: value

定义锚点（&）

env: *default

引用锚点（*）

env:
  <<: *default
  extra: value

合并锚点到当前字典（<<）

list: &list [a, b, c]

为列表定义锚点

copy: *list

引用列表锚点

config:
  <<: [*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:
  web:
    image: nginx:latest
    ports:
      - "80:80"

Docker Compose 服务定义

steps:
  - name: Checkout
    uses: actions/checkout@v4

GitHub Actions 步骤

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app

Kubernetes 资源定义

---
title: My Post
date: 2026-07-19
---

Front Matter（文章元信息）

env:
  DATABASE_URL: postgres://localhost/mydb

环境变量配置

参数矩阵

参数	作用	示例
`key: value`	键值对基本写法，冒号后必须有一个空格	`name: my-app`
`"string" / 'string'`	双引号支持转义，单引号不转义	`msg: "a\tb"`
`# 注释`	单行注释，从 # 到行尾	`# 生产环境端口`
`--- / ...`	文档分隔符与文档结束符，用于多文档	`---`
`null / ~`	显式空值，读取方不会报类型错误	`debug: null`
`0x1A / 0o17 / 0b1010`	十六 / 八 / 二进制整数写法	`mask: 0b1010`
`!!str 123 / !!int "42"`	类型强制转换，解开「全变字符串」的坑	`port: !!int "8080"`
`!!timestamp "..."`	把字符串解析为时间戳类型	`at: !!timestamp "2026-07-19"`
`\| 与 >`	\| 保留换行，> 把换行折叠成空格	`text: >`
`\|- / >- / \|+`	chomp 控制：去掉尾换行 / 保留尾空行	`text: \|-`
`&name 定义 / *name 引用`	锚点与别名，减少重复字面量	`env: *default`
`<<: *name`	合并键，把锚点字典并入当前节	`<<: *default`
`<<: [a, b]`	合并多个锚点，后者覆盖前者	`<<: [base, override]`
`- item / [a, b]`	块风格与流风格列表	`ports: - 80`
`{} 与 []`	显式空字典与空列表，避免读到 null	`config: {}`

易错点与避坑指南

现象解析器把整份文件当成一个字符串，键根本取不到

原因冒号后没留空格。YAML 要求 key: value，key:value 会被解析为纯标量文本。

处置把所有 key:value 统一改成 key: value，尤其注意 URL 片段和多行拼接处。

现象报 "found character that cannot start any token" 或缩进错误

原因YAML 对缩进敏感且不能用 Tab 缩进，同层级必须严格对齐。

处置把 Tab 全部换成等宽空格，并在编辑器里开启显示空白字符核对层级。

现象长段文字被拼成一行，反斜杠续行失效

原因反斜杠续行只适用于流风格（行内）标量；块风格的缩进行会在续行时保留换行符。

处置需要折叠为一行用 text: >，需要原样保留换行用 text: |。

现象用 << 合并后，后定义的同名键被锚点里的旧值覆盖

原因合并键的语义是「锚点里的值合并进来」，显式写在本节的同名键才是本地键，写在锚点里的同名键不参与覆盖。

处置要覆盖就在当前节直接写该键（不需要再写进被合并的锚点），多个锚点用 <<: [*base, *override] 并把 override 放最后。

现象环境变量 PORT=8080 读出来是字符串，端口校验失败

原因YAML 不会自动推断类型，外部传入的值默认按字符串解析。

处置用显式类型标签：port: !!int "${PORT}"。

现象值里带 : 或 # 的内容被截断，后半段消失

原因冒号后带空格、井号前有空格时会被当作键值分隔或注释起始。

处置把整个值用双引号或单引号包起来，需要保留转义时用双引号。

现象尾部多出一个空行，写入文件比对时不一致

原因块标量默认保留末尾换行；|2 这种显式缩进指示写法会按指定的 2 个空格推断内容缩进，不显式指定时以首行内容为准。

处置用 |- 去掉尾换行，用 |+ 明确要保留尾空行，团队内统一一种风格。

现象同样的配置在两个解析器上得到不同类型（一个是 int，一个是 str）

原因YAML 1.1 与 1.2 规范差异：1.1 会把 yes/no/on/off 当布尔、把前导 0 数字当八进制，部分解析器仍按 1.1 处理。

处置布尔值统一写 true / false，需要字符串 "yes" 时显式加引号。

排障路径

1确认锚点与合并键展开后的真实结果
cat config.yaml
锚点和合并键是纯语法糖，最终落地的是展开后的字面量。展开结果有歧义时，先把文件打印出来逐行核对。
2用 Python 校验 YAML 能否被解析并查看解析出的类型
python -c "import yaml,pprint; pprint.pprint(yaml.safe_load(open('config.yaml', encoding='utf-8')))"
能打印出 Python 字典/列表说明语法正确；报 ScannerError 时错误信息里的行号列号可直接定位。
3检查是否混用了 Tab 缩进
grep -Pn '\t' config.yaml
有输出即说明存在 Tab 缩进，需要全部替换为空格。
4排查冒号后缺空格的问题
grep -nE '^[ ]*[A-Za-z0-9_.-]+:[^ ]' config.yaml
匹配到的行是疑似漏空格的键值对，逐一确认是否需要补空格。
5校验多文档文件的每一段是否独立合法
python -c "import yaml; print(len(list(yaml.safe_load_all(open('config.yaml', encoding='utf-8')))))"
输出的文档数量应与文件中 --- 分隔符的数量一致，差 1 说明分隔符位置写错。

命令示例

用锚点合并复用公共配置

defaults: &defaults
  replicas: 2
  image: nginx:1.25
  env: production

app:
  <<: *defaults
  name: web

&defaults 定义锚点，<<: *defaults 把公共字段合并进 app；显式写的 name: web 覆盖同名锚点键。多服务复用公共配置时可避免逐段复制。

输出

解析后等价于：
app:
  name: web
  replicas: 2
  image: nginx:1.25
  env: production

Docker Compose 端口映射要加引号

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      NGINX_PORT: "80"

ports 里的 "8080:80" 必须加双引号，否则冒号加数字会被解析成序列语法而报错；environment 中的值想保留字符串语义时同样建议加引号。

常见坑与注意事项

缩进必须一致：同一层级不混用空格数量、更不能使用 Tab，否则解析器报错或产生意外的深层嵌套。
冒号后必须有空格（key: value），否则整行被当字符串处理，配置静默不生效。
值以 : # @ 等特殊字符开头时需加引号，避免被当成标签、注释或锚点语法。
日期与数字会被自动类型推断（2026-07-19 会解析成 Date），需要字符串语义时主动加引号。
<< 合并键的优先级低于显式键：同名键以显式定义为准，不要指望锚点能覆盖已写的值。

提示

YAML 对缩进敏感，必须用空格不能用 Tab，同一层级必须对齐。
冒号后必须有空格（key: value），否则会被解析为字符串。
多行字符串用 | 保留换行，用 > 折叠换行（适合长段落）。
字符串含特殊字符（: # @ ` 等）时需加引号，避免解析歧义。
锚点 & 定义、别名 * 引用、<< 合并键可减少重复配置。
多文档用 --- 分隔，常见于 Front Matter 和 CI/CD 配置。

常见问题

为什么 key: value 少写一个空格就被解析成字符串？

YAML 规定冒号后必须跟一个空格才算键值分隔。写成 url:localhost:3306 时，整行会被当作一个普通标量字符串，读取 map 时就拿不到 key。正确写法是 url: localhost:3306；如果值本身带冒号又不想被误读，用双引号包起来 key: "value: with colon"。同理 Tab 不能用于缩进，必须用空格且同层对齐。

多行文本该用竖线 | 还是大于号 >？

看你要不要保留原文换行。text: | 是 Literal 标量，逐行原样保留换行，适合代码块、配置片段；text: > 是 Folded 标量，把连续换行折叠成一个空格，适合长段落说明。两者都可加 chomp 修饰符：|2 指定缩进指示数字，|- 保留换行但去掉末尾换行，>- 折叠并去尾换行。需要精确控制时用双引号写 text: "line1\nline2"。

锚点 &、别名 * 和合并键 << 什么时候值得用？

同一份默认值要在一堆地方重复时用它。先用 default: &default 定义锚点，别处写 env: *default 引用；想把锚点当基底再叠加局部覆盖，用合并键 env:\n <<: *default\n extra: value。多个锚点还能一次合并：config:\n <<: [*base, *override]，后者覆盖前者。列表同样可以锚定：list: &list [a, b, c] 之后 copy: *list。

配置里的数字和布尔被读成字符串，怎么强制类型？

在值前面加显式标签即可：key: !!str 123 把整数 123 变字符串，reverse 方向同样成立。常用标签还有 !!int "42" 字符串转整数、!!float "3.14" 转浮点、!!bool "yes" 转布尔、!!timestamp "2026-07-19" 转时间戳、!!null "" 把空串转成 null。也可以用 !!seq {} / !!map [] 显式声明序列或映射类型，避免下游把它当字符串。

一个文件里写了好几份配置，--- 分隔符该怎么用？

--- 是文档分隔符，把一个文件切成多个独立文档，每个文档有自己的顶层结构，解析器一次可拿到文档列表。典型场景是 Front Matter：文件开头先写 ---，里面放 title: My Post 和 date: 2026-07-19，再用 --- 收尾，正文当作第二份文档。... 标记文档显式结束。多文档常出现在 CI/CD 与 Kubernetes 配置里，每个 --- 之后是一份独立资源定义。

官方参考来源

下方为命令对应的官方权威文档，供你核对最新用法与深入查阅。

YAML 规范

由巧匠维护

公开更新于 2026年7月21日，内容持续校对官方文档。

联系我们

命令或描述有误？提交反馈、商务合作或产品建议都可发送邮件给我们。

联系我们

典型使用场景

基础语法 Basic Syntax 8

数据类型 Data Types 8

列表 List / Array 6

字典 Dictionary / Object 6

多行字符串 Multiline String 7

锚点与引用 Anchor & Alias 6

类型强制转换 Type Conversion 8

实用示例 Real-world Examples 5

参数矩阵

易错点与避坑指南

排障路径

命令示例

用锚点合并复用公共配置

Docker Compose 端口映射要加引号

常见坑与注意事项

提示

常见问题

相关速查表

分享

官方参考来源

由 巧匠 维护

联系我们

由巧匠维护