如何高效使用 ruamel.yaml 保持 YAML 文件格式一致性？

在Python里处理YAML文件时，标准库yaml在读写后往往会丢掉注释、改变缩进或调整引号，导致版本差异混乱。ruamel.yaml专门解决了这个问题，它能在修改数据的同时保留原文件格式。下面先看一张示例图了解基本工作流。

为什么选择 ruamel.yaml

很多配置由人工编写，带有说明性注释和特定排版。使用普通库转储会生成机器风格内容。ruamel.yaml的设计目标就是往返（round-trip）安全，即加载后再保存，内容和样式尽量一致。

安装与基础使用

通过pip即可安装：

pip install ruamel.yaml

以下示例展示如何读取YAML、修改一个值并写回，同时保持格式：

from ruamel.yaml import YAML

# 创建YAML对象，设置保留格式
yaml = YAML()
yaml.preserve_quotes = True  # 保留引号风格
yaml.indent(mapping=2, sequence=4, offset=2)  # 自定义缩进

# 读取文件
with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.load(f)

# 修改内容，注释和其余结构不变
data['database']['port'] = 5433

# 写回文件
with open('config.yaml', 'w', encoding='utf-8') as f:
    yaml.dump(data, f)

关键参数说明

为了保持一致性，可关注如下设置：

• preserve_quotes：保留字符串原有的单双引号。
• width：控制换行宽度，默认80，设大可避免意外折行。
• indent：分别设置映射、序列缩进与偏移。

处理多文档与流式写入

若YAML含多个文档，可使用yaml.load_all与yaml.dump_all。注意在代码里函数调用为load_all()，不是标签形式。

from ruamel.yaml import YAML

yaml = YAML()
docs = list(yaml.load_all(open('multi.yaml', encoding='utf-8')))
docs[0]['changed'] = True
yaml.dump_all(docs, open('multi_out.yaml', 'w', encoding='utf-8'))

常见误区

不要使用 yaml.dump 来自标准库覆盖 ruamel 读出的对象，那样会丢失格式信息。

另外，在正文描述HTML标签时应转义，例如提到输入框元素要写<input>而非真实标签。用code标签标代码术语时，内部如<string>也需转义。

小结

合理设置 ruamel.yaml 的参数，就能在程序化修改 YAML 时维持人工编辑的格式一致性，减少不必要的代码评审噪音。

ruamel.yamlYAML_formatPython修改时间：2026-07-29 08:39:17