本文详解如何利用 ruamel.yaml 的块标量（block scalars）和 preserve_quotes/default_flow_style 等配置，在 round-trip 加载-修改-转储过程中无损保留原始换行结构，解决长行误折叠、缩进丢失等常见问题。
本文详解如何利用 ruamel.yaml 的块标量（block scalars）和 `preserve_quotes`/`default_flow_style` 等配置，在 round-trip 加载-修改-转储过程中**无损保留原始换行结构**，解决长行误折叠、缩进丢失等常见问题。
在使用 ruamel.yaml 进行 YAML 文件的读取—修改—写入（round-trip）操作时，一个高频痛点是：原始文件中人为换行的字符串（如 description: This is... 跨行书写）在 load() 后丢失换行信息，导致 dump() 输出时被强制展平或错误折行。根本原因在于 YAML 规范对流式标量（flow scalars） 的定义——所有流式字符串（即用 : 直接后接值的普通形式）中的换行符默认被“折叠”（folded），即视为空格处理。这意味着 ruamel.yaml 在解析阶段已将换行逻辑丢弃，后续无法还原。
要真正保留换行，必须让 YAML 解析器识别并保留换行语义，这只能通过 块标量（block scalars） 实现。块标量以 |（literal）或 >（folded）开头，明确告诉解析器：其后内容的换行具有结构意义，需完整保留。
✅ 正确做法：显式声明块标量格式
将原始 YAML 中需保留换行的字段改为块标量语法：
description: |- This is a long line that has been wrapped. url: https://long-url.com/add-more-characters-so-that-it-goes-out-farther-than-the-default-80-cols value: 7
注意 |-（带减号的 literal block scalar）：它会保留所有换行和空格，但去除末尾空白行，最贴近人工换行的语义。对比 |（保留末尾空行）和 >（折叠内部换行为空格），|- 是多数场景下的首选。
对应 Python 代码需启用 preserve_quotes 并合理配置 width，确保 dump 时不破坏已有格式：
import ruamel.yaml import sys yaml = ruamel.yaml.YAML() yaml.preserve_quotes = True # 保留原始引号（如单/双引号） yaml.width = 999 # 禁用自动折行长行（仅影响非块标量） yaml.indent(mapping=2, sequence=4, offset=2) instr = """\ description: |- This is a long line that has been wrapped. url: https://long-url.com/add-more-characters-so-that-it-goes-out-farther-than-the-default-80-cols value: 7 """ data = yaml.load(instr) data['value'] += 1 yaml.dump(data, sys.stdout)
输出将严格保持原始换行：
description: |- This is a long line that has been wrapped. url: https://long-url.com/add-more-characters-so-that-it-goes-out-farther-than-the-default-80-cols value: 8
⚠️ 关键注意事项
- yaml.width = 999 仅作用于流式标量：它不能恢复已丢失的换行信息，仅防止新生成的长行被折行。块标量的换行由其自身语法控制，不受 width 影响。
- preserve_quotes=True 必须开启：否则 ruamel.yaml 可能将原始带引号的字符串（如 "value": "7"）转为无引号形式，造成格式漂移。
- 避免混用流式与块式语义：若原始文件未使用 | 或 >，则 ruamel.yaml 无法逆向推断换行意图。块标量是唯一可信赖的换行保留机制。
- 编辑器友好提示：建议在团队 YAML 规范中约定：所有可能跨行的文本字段（如 description, summary, notes）统一采用 |- 块标量，既提升可读性，又保障工具链兼容性。
总结
保留 YAML 换行不是靠调参，而是靠符合规范的显式语法。ruamel.yaml 的强大之处在于它严格遵循 YAML 1.2 规范，而规范早已为换行保留提供了标准方案——块标量。通过将目标字段改写为 |- 格式，并配合 preserve_quotes=True 和合理的 indent/width 设置，即可实现真正的 round-trip 格式保真。记住：解析阶段的信息完整性，决定 dump 阶段的还原能力；不声明块标量，就永远无法找回换行。
