把多行说明或脚本写进YAML,排版看着一样,转成JSON后却出现了空格或不同数量的 \n。问题通常不在缩进好不好看,而在于块标量的写法决定了哪些换行属于最终字符串。

本文用YAML/JSON互转逐组比较 |、>、|-、|+ 和中间空行。演示文本只有alpha、beta,不运行脚本,也不把样例用于真实部署。

先比较普通两行文本

左侧输入:

literal: |
  alpha
  beta
folded: >
  alpha
  beta

点击“转换为 JSON”。

竖线样例保留两行间的换行,大于号样例把这处换行折叠成空格
竖线样例保留两行间的换行,大于号样例把这处换行折叠成空格

本次 literal 的输出是 "alpha\nbeta\n",folded 是 "alpha beta\n"。这里展示的是JSON源码,反斜杠n表示解析后的LF字符,不是值中一定包含两个普通字符。两组末尾都还有一个换行。

| 适合希望保留这些行分隔的内容;> 会对这种普通相邻行进行折叠。如果是一条需要完整保持换行的文本,不能因为大于号让配置看起来紧凑,就假定它与竖线得到同样的字符串。

这只是普通相邻行样例。折叠规则还会考虑空行和更深缩进,不能把 > 简化成“把所有回车都换为空格”。下一组继续单独核对末尾,避免同时改动几个条件后难以判断差别。

减号和加号影响末尾

第二组输入中,keep 的beta后面保留两次回车,也就是再留一个空行:

strip: |-
  alpha
  beta
keep: |+
  alpha
  beta
strip结果没有末尾换行,keep结果保留了本次输入末尾的两个换行
strip结果没有末尾换行,keep结果保留了本次输入末尾的两个换行

本次 strip 输出 "alpha\nbeta",keep 输出 "alpha\nbeta\n\n"。|- 去掉末尾换行;|+ 保留本次存在的尾部换行和空行。加号并不是无论输入怎样都固定增加两个换行,结果还取决于输入末尾实际有多少。

普通 | 的默认处理与这两种又有区别:第一组保留一个末尾换行,没有把所有尾部空行原样带上。排查摘要、签名或逐字比较不一致时,末尾一个看不见的LF就足以让字节不同。

复制代码块时,编辑器可能对最后一行做处理。本段的结论应以图中实际转换结果为准;复测自己的配置时,确认beta后面的回车是否真的保留下来,不要只靠光标看起来在下一行判断数量。

大于号也会保留某些换行

第三组在alpha和beta之间加一个空行:

folded: >-
  alpha

  beta
literal: |-
  alpha

  beta
中间有空行时,本次folded保留一个换行,literal保留两个换行
中间有空行时,本次folded保留一个换行,literal保留两个换行

这次 folded 是 "alpha\nbeta",literal 是 "alpha\n\nbeta",两者末尾都没有LF。可见大于号并未删除所有行分隔;竖线也没有把一个空行当成“完全没有内容”而丢掉。

在应用中需要两段文字时,要先明确段落之间应有几个换行,再选择标量方式。若下游程序会继续渲染Markdown、拆分命令行或拼接模板,还要看它对换行的实际处理;这次转换只说明得到的字符串,不保证最终页面或脚本行为。

检查时可以把JSON结果交给解析器,再查看字符串长度、末尾字符及换行位置。不要直接在配置中全局替换竖线和大于号,也不要先删空行再比较,那样已经改变了输入。

需要先核对YAML的对象与列表结构,可以参照基础双向转换说明。多行文本则应额外保留一份原文和预期值,让接手的人能确认“保留哪些换行”也是配置内容的一部分。