illegalCreed

中文

English

中文

English

Appearance

标量与字符串：引号、块标量与 chomping ​

基于 YAML 1.2.2 · 核于 2026-07

速查 ​

  • 五种标量样式：普通 plain（不加引号）、单引号、双引号、字面块 |、折叠块 >。
  • 普通标量：最简洁，但不能含某些特殊字符、不能转义，且可能被类型推断误判；不确定时加引号。
  • 单引号 '...'：几乎不转义，内容按字面；唯一转义是 '' 表示一个字面单引号；'\n' 是反斜杠加 n 两个字面字符。
  • 双引号 "..."：支持完整转义 \n \t \" \\ \uXXXX \U00XXXXXX；需要真换行/制表/Unicode 时必须用它。
  • 字面块 |（literal）：保留块内所有换行，原样成为多行字符串；适合脚本、日志模板。
  • 折叠块 >（folded）：把普通行的换行折叠成空格，空行转成真换行，更深缩进行的换行保留；适合长段落。
  • chomping 削减指示符（控制块标量末尾换行）：- strip 全删、默认 clip 保留一个、+ keep 全部保留。可与缩进指示组合，如 |-、>+、|2。
  • 显式标签：!!str/!!int/!!float/!!bool/!!null 强制类型，覆盖默认推断（如 !!str 42 得字符串）。
  • 多行字符串首选：写 shell 脚本/配置模板用 |（保留换行）；写长描述用 >（折叠成一段）。
  • ⚠️ 注释不能进标量内部；普通/单引号标量里的 # 视上下文可能被当字符串字符，行内注释需前置空白。

一、三种单行标量样式 ​

同一个字符串，可以用三种单行样式写，差别在转义能力和特殊字符容忍度：

yaml
plain:  hello world              # 普通标量：最简洁
single: 'it''s a "test"'         # 单引号：内含 '' → 一个字面单引号，双引号原样
double: "line1\nline2\ttab"      # 双引号：\n 变真换行，\t 变制表符

选择依据：

样式转义何时用
普通 plain不支持简单值、不含特殊字符、不会被类型误判时
单引号仅 ''→'值含 : # 等特殊字符，但不需要转义序列时
双引号完整（\n 等）需要换行、制表、Unicode 转义时

单引号里的反斜杠是字面

'C:\path\new' 里的 \n 不是换行，而是反斜杠加字母 n 两个字面字符；"C:\path\new" 里的 \n 会被解析成一个真换行符（且 \p 是非法转义）。写 Windows 路径、正则时优先用单引号或普通标量，避免双引号的意外转义。

二、字面块 |：保留换行 ​

竖线 | 引导字面块标量：块内的每一个换行都被原样保留，成为字符串的一部分。这是写多行脚本、模板、带格式文本的首选：

yaml
script: |
  #!/bin/bash
  echo "line 1"
  echo "line 2"
  exit 0

上面 script 的值是一个包含 4 行、行间带换行的字符串。CI 配置里写多行 shell 命令几乎都用 |。

三、折叠块 >：折叠换行为空格 ​

大于号 > 引导折叠块标量：块内普通行之间的换行被折叠成一个空格，从而把多行拼成一段连续文本；而空行会转成一个真正的换行（用于分段），比基准缩进更深的行（more-indented）其换行则会保留（可内嵌代码/列表片段）：

yaml
description: >
  这是一段很长的说明文字，
  在源码里换行只是为了方便阅读，
  解析后会被折叠成一整段（换行变空格）。

  空行会变成真正的段落分隔。

description 解析后是：这是一段很长的说明文字， 在源码里换行只是为了方便阅读， 解析后会被折叠成一整段（换行变空格）。\n空行会变成真正的段落分隔。（前三行拼成一段，空行处保留换行）。

一句话记忆：| 保留换行（literal，所见即所得）；> 折叠换行为空格（folded，适合长段落）。

四、chomping：控制块标量末尾的换行 ​

块标量末尾往往有换行，YAML 用 chomping 削减指示符控制怎么处理它，三种取值：

指示符名称末尾换行处理
-strip删掉所有末尾换行（一个都不留）
无（默认）clip保留单个末尾换行，去掉多余空行
+keep保留全部末尾换行（含结尾空行）
yaml
strip:  |-
  no trailing newline
clip:   |
  one trailing newline
keep:   |+
  all trailing newlines


literal_with_indent: |2
    这里用 |2 显式指定缩进为 2，避免自动探测歧义
  • |-（strip）：拼接命令、不希望结尾多出换行时常用；
  • |（clip，默认）：最常见，保留一个收尾换行；
  • |+（keep）：需要精确保留末尾多个空行时用；
  • 块标量还能加缩进指示数字（如 |2、>1），在首行本身就有前导空格、自动缩进探测有歧义时显式指定缩进量。

五、显式类型标签：强制覆盖推断 ​

当默认类型推断不合心意时，用 !! 开头的显式标签强制类型：

yaml
force_string: !!str 42        # 强制字符串 "42"（否则会是整数 42）
force_int:    !!int "100"     # 强制整数 100
force_float:  !!float 3       # 强制浮点 3.0
force_null:   !!null ~        # 显式 null
force_bool:   !!bool "true"   # 强制布尔 true

!! 是内置默认标签前缀 tag:yaml.org,2002: 的简写，所以 !!str 展开是完整标签 tag:yaml.org,2002:str。自定义标签则用单个 ! 前缀（如 !MyType），由具体应用/解析器解释。显式标签最常见的用途就是把形似数字/布尔的值强制成字符串，是对付隐式类型推断坑的利器（详见类型、Schema 与坑）。

标量搞定后，下一步进入 集合与文档结构：块式/流式序列与映射的完整写法、嵌套技巧、复杂键 ?，以及多文档流。