基础设施即代码 / 知识点
YAML 语法速查手册
类型、Schema 与显式 Tag
!<TAG> <NODE> / !name <NODE>给节点附加应用自定义类型标记。
自定义 Tag
给节点附加应用自定义类型标记。
所属主题
类型、Schema 与显式 Tag
语法 / 形式
!<TAG> <NODE> / !name <NODE>推荐示例
value: !Secret encrypted-data关键边界
具体含义完全由应用/解析框架定义,不能假设跨工具兼容。
plain scalar + schema未加引号标量最终解析成何种类型由 schema/应用决定。
Schema 决定隐式类型
未加引号标量最终解析成何种类型由 schema/应用决定。
所属主题
类型、Schema 与显式 Tag
语法 / 形式
plain scalar + schema推荐示例
value: 123关键边界
YAML 语法合法不代表不同解析库得到的宿主类型完全一致。
Anchor、Alias 与复用
&<NAME>给当前节点定义可被别名引用的 anchor。
定义 Anchor
给当前节点定义可被别名引用的 anchor。
所属主题
Anchor、Alias 与复用
语法 / 形式
&<NAME>推荐示例
defaults: &defaults
timeout: 30
retries: 3关键边界
Anchor 是序列化层标签,不是业务数据字段。
*<NAME>引用之前定义的 anchor 节点。
引用 Alias
引用之前定义的 anchor 节点。
所属主题
Anchor、Alias 与复用
语法 / 形式
*<NAME>推荐示例
prod: *defaults关键边界
Alias 引用的是节点,而不是普通字符串替换。
&<NAME> { ... }给 Mapping 定义 anchor。
Mapping Anchor
给 Mapping 定义 anchor。
所属主题
Anchor、Alias 与复用
语法 / 形式
&<NAME> { ... }推荐示例
base: &base
host: localhost
port: 8080关键边界
常见于重复配置复用。
&<NAME> [ ... ]Sequence 也可以被 anchor。
Sequence Anchor
Sequence 也可以被 anchor。
所属主题
Anchor、Alias 与复用
语法 / 形式
&<NAME> [ ... ]推荐示例
ports: &ports [80, 443]
publicPorts: *ports关键边界
是否在宿主对象中共享引用语义取决于解析器。
&name ... *nameAlias 必须引用当前文档中此前已定义的 anchor。
Anchor 名称作用域
Alias 必须引用当前文档中此前已定义的 anchor。
所属主题
Anchor、Alias 与复用
语法 / 形式
&name ... *name推荐示例
base: &base {x: 1}
copy: *base关键边界
跨 --- 文档不能直接引用前一个文档的 anchor。
*aliasAlias 复用 YAML 节点,不执行 ${VAR} 等变量替换。
Alias 不是变量插值
Alias 复用 YAML 节点,不执行 ${VAR} 等变量替换。
所属主题
Anchor、Alias 与复用
语法 / 形式
*alias推荐示例
copy: *base关键边界
环境变量插值属于 Docker Compose、Helm、应用框架等上层能力。
<<: *<ANCHOR>很多解析器支持把 Mapping 内容合并进当前 Mapping。
Merge Key <<
很多解析器支持把 Mapping 内容合并进当前 Mapping。
所属主题
Anchor、Alias 与复用
语法 / 形式
<<: *<ANCHOR>推荐示例
prod:
<<: *defaults
timeout: 60关键边界
这是历史 YAML merge key/生态能力,不应当作 YAML 1.2 core schema 的普通标准语法依赖;跨解析器要验证。
<<: *base
key: override常见 merge 实现中显式本地键覆盖合并进来的键。
Merge Key 覆盖
常见 merge 实现中显式本地键覆盖合并进来的键。
所属主题
Anchor、Alias 与复用
语法 / 形式
<<: *base
key: override推荐示例
prod:
<<: *defaults
retries: 5关键边界
属于 merge extension 行为,目标解析器必须实际支持。
<<: [*a, *b]部分实现支持一次 merge 多个 Mapping。
多个 Mapping Merge
部分实现支持一次 merge 多个 Mapping。
所属主题
Anchor、Alias 与复用
语法 / 形式
<<: [*a, *b]推荐示例
config:
<<: [*base, *region]关键边界
优先级细节容易误解且兼容性有限,生产配置建议避免复杂 merge 链。
文档边界、指令与注释
---标识 YAML document 开始,也用于 stream 中分隔多个文档。
文档开始标记
标识 YAML document 开始,也用于 stream 中分隔多个文档。
所属主题
文档边界、指令与注释
语法 / 形式
---推荐示例
---
name: first关键边界
单文档文件可以省略,但 Kubernetes 等生态常显式使用。
...显式标记当前 YAML document 结束。
文档结束标记
显式标记当前 YAML document 结束。
所属主题
文档边界、指令与注释
语法 / 形式
...推荐示例
---
name: first
...关键边界
普通配置文件很少需要;流式传输场景更有意义。
--- ... ---一个 YAML stream 可包含多个 document。
多文档 Stream
一个 YAML stream 可包含多个 document。
所属主题
文档边界、指令与注释
语法 / 形式
--- ... ---推荐示例
---
name: first
---
name: second关键边界
应用是否接受多文档由上层工具决定。
# <COMMENT># 开始注释直到行尾。
行注释
# 开始注释直到行尾。
所属主题
文档边界、指令与注释
语法 / 形式
# <COMMENT>推荐示例
port: 8080 # application port关键边界
在 plain scalar 内,# 成为注释通常要求前面有 separation whitespace。
# <COMMENT>整行可以只写注释。
整行注释
整行可以只写注释。
所属主题
文档边界、指令与注释
语法 / 形式
# <COMMENT>推荐示例
# production settings
replicas: 3关键边界
注释属于 presentation,不是 representation graph 数据。
%YAML <MAJOR>.<MINOR>声明文档使用的 YAML 版本。
YAML 版本指令
声明文档使用的 YAML 版本。
所属主题
文档边界、指令与注释
语法 / 形式
%YAML <MAJOR>.<MINOR>推荐示例
%YAML 1.2
---
name: demo关键边界
指令必须出现在 document 起始位置,并与 --- 配合;日常配置极少需要。
%TAG <HANDLE> <PREFIX>为 tag URI 定义简写 handle。
TAG 指令
为 tag URI 定义简写 handle。
所属主题
文档边界、指令与注释
语法 / 形式
%TAG <HANDLE> <PREFIX>推荐示例
%TAG !e! tag:example.com,2026:
---
value: !e!Type data关键边界
属于高级序列化能力,普通配置不需要。
特殊字符与易错边界
<TAB>YAML block indentation 使用空格,不应使用 Tab 作为 indentation。
Tab 不能用于结构缩进
YAML block indentation 使用空格,不应使用 Tab 作为 indentation。
所属主题
特殊字符与易错边界
语法 / 形式
<TAB>推荐示例
app:
name: demo关键边界
Tab 可以出现在某些标量内容中,但不要用于层级缩进。
:在 block mapping 中用于分隔 key/value。
冒号 + 空格的结构含义
在 block mapping 中用于分隔 key/value。
所属主题
特殊字符与易错边界
语法 / 形式
: 推荐示例
name: demo关键边界
字符串内容含 : 时加引号最稳。