基础设施即代码 / 知识点
YAML 语法速查手册
特殊字符与易错边界
#在 separation context 中开始注释。
井号的注释含义
在 separation context 中开始注释。
所属主题
特殊字符与易错边界
语法 / 形式
#推荐示例
password: 'abc#123'关键边界
无引号敏感文本出现 # 容易被截断。
-在 block context 中表示 sequence entry。
短横线 + 空格的列表含义
在 block context 中表示 sequence entry。
所属主题
特殊字符与易错边界
语法 / 形式
- 推荐示例
items:
- one
- two关键边界
字符串以 - 开头时应加引号。
?用于显式 mapping key。
问号的显式 Key 含义
用于显式 mapping key。
所属主题
特殊字符与易错边界
语法 / 形式
? 推荐示例
? complex key
: value关键边界
普通字符串以特殊指示符开头时应考虑加引号。
*<ANCHOR>* 开头节点会被解释为 alias。
星号的 Alias 含义
* 开头节点会被解释为 alias。
所属主题
特殊字符与易错边界
语法 / 形式
*<ANCHOR>推荐示例
value: '*literal'关键边界
如果只是普通星号文本,应加引号。
&<ANCHOR>& 开头用于定义 anchor。
与号的 Anchor 含义
& 开头用于定义 anchor。
所属主题
特殊字符与易错边界
语法 / 形式
&<ANCHOR>推荐示例
value: '&literal'关键边界
普通文本以 & 开头时加引号。
!<TAG>! 用于 tag。
感叹号的 Tag 含义
! 用于 tag。
所属主题
特殊字符与易错边界
语法 / 形式
!<TAG>推荐示例
value: '!important'关键边界
普通字符串以 ! 开头时应加引号。
{} / []在 flow context 表示 mapping/sequence。
花括号/方括号的 Flow 含义
在 flow context 表示 mapping/sequence。
所属主题
特殊字符与易错边界
语法 / 形式
{} / []推荐示例
pattern: '[a-z]+'关键边界
正则或字面文本以这些符号表达时加引号更安全。
,在 flow collection 中分隔元素。
逗号在 Flow 中的含义
在 flow collection 中分隔元素。
所属主题
特殊字符与易错边界
语法 / 形式
,推荐示例
items: [a, b, c]关键边界
block style 中逗号一般只是 scalar 内容。
UTF-8 BOMYAML stream 可以涉及 Unicode BOM,但工程配置通常不应主动加入。
BOM
YAML stream 可以涉及 Unicode BOM,但工程配置通常不应主动加入。
所属主题
特殊字符与易错边界
语法 / 形式
UTF-8 BOM推荐示例
encoding: UTF-8关键边界
不同工具链对 BOM 处理体验不一致,UTF-8 无 BOM 最通用。
LF / CRLFYAML 规范支持行分隔,但工具链可能在 Git/容器环境表现不同。
换行风格
YAML 规范支持行分隔,但工具链可能在 Git/容器环境表现不同。
所属主题
特殊字符与易错边界
语法 / 形式
LF / CRLF推荐示例
lineEnding: LF关键边界
工程仓库建议统一 LF,减少 diff 和 shell 嵌入文本问题。
常用配置结构
mapping使用顶层 Mapping 表示配置对象。
简单应用配置
使用顶层 Mapping 表示配置对象。
所属主题
常用配置结构
语法 / 形式
mapping推荐示例
app:
name: anystack
port: 8080
enabled: true关键边界
多数配置文件推荐从 mapping 开始。
sequence of mappings使用对象列表表达同构配置项。
环境列表
使用对象列表表达同构配置项。
所属主题
常用配置结构
语法 / 形式
sequence of mappings推荐示例
servers:
- name: api-1
host: 10.0.0.1
- name: api-2
host: 10.0.0.2关键边界
不要用动态 key 模拟列表,除非 key 本身有业务意义。
mapping → mapping按领域分组键值。
嵌套配置
按领域分组键值。
所属主题
常用配置结构
语法 / 形式
mapping → mapping推荐示例
database:
host: db.example.com
port: 5432
pool:
min: 2
max: 20关键边界
控制嵌套深度,避免配置树过深。
sequence of scalars用 Sequence 表示有序字符串集合。
字符串列表
用 Sequence 表示有序字符串集合。
所属主题
常用配置结构
语法 / 形式
sequence of scalars推荐示例
features:
- search
- billing
- notifications关键边界
如果顺序无业务意义,上层应用仍不应依赖排列。
flow sequence短且简单的列表可写成一行。
短列表使用 Flow
短且简单的列表可写成一行。
所属主题
常用配置结构
语法 / 形式
flow sequence推荐示例
ports: [80, 443]关键边界
超过少量元素后 block style 通常更易读。
block scalar |脚本、证书、SQL 等多行文本使用 |。
长文本使用 Literal
脚本、证书、SQL 等多行文本使用 |。
所属主题
常用配置结构
语法 / 形式
block scalar |推荐示例
sql: |
SELECT id, name
FROM users
WHERE active = true;关键边界
能避免大量 \n 转义。
block scalar >自然语言说明可用 > 折叠。
长说明使用 Folded
自然语言说明可用 > 折叠。
所属主题
常用配置结构
语法 / 形式
block scalar >推荐示例
description: >
This service handles
background jobs.关键边界
解析后通常成为一行式文本。
quotes对于 ID、版本、端口字符串、日期字符串等显式加引号。
明确字符串类型
对于 ID、版本、端口字符串、日期字符串等显式加引号。
所属主题
常用配置结构
语法 / 形式
quotes推荐示例
version: '1.0'
userId: '00123'
release: '2026-08-27'关键边界
减少隐式 schema/解析库差异。
<EXTERNAL_SECRET_REFERENCE>YAML 文件本身不提供秘密保护。
不要在 YAML 中存明文 Secret
YAML 文件本身不提供秘密保护。
所属主题
常用配置结构
语法 / 形式
<EXTERNAL_SECRET_REFERENCE>推荐示例
passwordFrom: secret-manager://prod/db-password关键边界
是否加引号与是否加密无关;Git 中的 YAML Secret 仍是明文数据。
application semanticsYAML 只描述数据,不定义环境变量默认值、条件逻辑或继承。
配置默认值由应用处理
YAML 只描述数据,不定义环境变量默认值、条件逻辑或继承。
所属主题
常用配置结构
语法 / 形式
application semantics推荐示例
timeout: 30关键边界
${VAR:-default}、模板 if/for 等属于上层系统。