集合与文档结构：序列、映射与多文档

基于 YAML 1.2.2 · 核于 2026-07

速查

• 两类集合：序列 sequence（有序列表）与映射 mapping（无序键值对），各有块式/流式两种写法。
• 块式序列：每行 - item（短横线后空格）；同缩进层构成一个列表；元素可为标量/映射/嵌套序列。
• 块式映射：key: value（冒号后空格）；子结构靠更深缩进表达。
• 流式序列/映射：[a, b, c] / {k1: v1, k2: v2}，借自 JSON，适合短小内容写一行。
• 序列套映射（最常用）：- key: value 起头，同元素其余键缩进对齐——k8s/CI 描述「一组带属性的条目」的标准结构。
• 映射套序列：键的值缩进后写 - 列表。
• 复杂键 ?：用 ? 键 + : 值 让键本身是多行标量、序列或映射。
• 集合 set：? item（键无值，值为 null）或流式 {a, b, c}，表示无重复元素的集合。
• 多文档：--- 分隔文档起始，... 标记文档结束；k8s 多资源清单常用。
• 空结构：空映射 {}、空序列 []；键后留空 → 值为 null。
• ⚠️ 别把序列和映射缩进搞混：- 是序列元素，key: 是映射键，二者在同一父节点下不能混用同层。

一、序列：块式与流式

序列是有序的值列表：

# 块式序列：每个元素 - 开头，同缩进层
languages:
  - Python
  - JavaScript
  - Go

# 流式序列：方括号加逗号，一行写完
languages: [Python, JavaScript, Go]

# 元素可以是任意类型：标量、映射、嵌套序列
matrix:
  - [1, 2, 3]
  - [4, 5, 6]

二、映射：块式与流式

映射是无序的键值对集合：

# 块式映射
person:
  name: Alice
  age: 30
  active: true

# 流式映射
person: { name: Alice, age: 30, active: true }

映射的键通常是标量字符串，值可以是标量、序列或另一个映射（嵌套）。

三、嵌套：序列套映射、映射套序列

真实配置几乎都是嵌套结构，两种组合最常见：

# ① 序列套映射：列表的每个元素是一个对象（k8s/CI 最常见）
containers:
  - name: web
    image: nginx:latest
    ports:
      - 80
      - 443
  - name: db
    image: postgres:16

# ② 映射套序列：某个键的值是一个列表
service:
  name: api
  tags:
    - backend
    - critical

要点：序列元素是映射时，把 - 和该映射的第一个键写在同一行（- name: web），其余键缩进对齐到 name 的位置。同一个 - 下缩进对齐的多个键，构成序列里的一个映射元素。

序列与映射不能在同层混用

同一个父节点下，要么全是 - 序列元素，要么全是 key: 映射键，不能一半列表一半键值对。混用会导致解析错误或结构不符合预期。

四、复杂键与集合

复杂键 ?

当映射的键本身需要是多行标量、序列或映射（而不是简单字符串）时，用问号 ? 显式标记键、冒号 : 标记值：

# 键是一个序列
? - Manchester United
  - Real Madrid
: [2001-01-01, 2002-02-02]

# 键是多行文本
? |
  这是一个
  多行的键
: 它对应的值

日常配置里简单标量键占绝大多数，?/: 复杂键是键为复合结构时的标准解法。

集合 set

YAML 用「键存在、值为 null」的映射表示集合（set），即一组无重复元素：

# 块式：每个元素用 ? 标记（值省略即 null）
tags:
  ? backend
  ? critical
  ? urgent

# 等价于值都为 null 的映射
tags:
  backend: null
  critical: null

# 流式集合
tags: {backend, critical, urgent}

五、多文档流

一个 YAML 文件（流）可以包含多个文档，用 --- 分隔——这是 Kubernetes 把多个资源对象写进一个清单文件的方式：

# 文档 1
apiVersion: v1
kind: Service
metadata:
  name: my-service
---
# 文档 2
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
...

• ---：文档起始分隔符（文件开头的第一个 --- 可省略）；
• ...：文档结束标记（可选，主要用于通信管道场景，表示当前文档到此为止但不开启新文档）；
• 解析多文档时，库通常提供「加载全部文档」的接口（如 js-yaml 的 loadAll、PyYAML 的 load_all）。

锚点/别名的作用域限于单个文档

后面会讲的锚点 & 和别名 * 不能跨 --- 文档引用——别名只能引用同一文档内、且在它之前定义的锚点。跨文档复用要靠程序层面处理。

---

结构搭好后，下一步进入 锚点、别名与合并键：用 &/*/<< 消除重复配置，以及它们的作用域与常见坑。