使用ruamel.yaml实现嵌套字典自动dump时，如何避免YAML文件被重新格式化？

阿华AIGC实验室

2026-5-1

解决ruamel.yaml自动dump时丢失格式、注释和键顺序的问题

你遇到的问题核心在于使用了safe模式加载YAML，以及将自定义字典转成普通dict再dump——这两种操作都会丢失原YAML文档的格式元信息（注释、键顺序、缩进风格）。下面是具体的解决方案：

问题根源拆解

typ="safe"模式的局限：这个模式只负责安全解析YAML的数据结构，完全不保留原文档的注释、键的插入顺序和缩进配置，加载后得到的是普通Python字典（即使Python3.7+字典有序，ruamel.yaml的safe dump仍会强制按字母排序键）。
转成普通dict dump：你的dump方法里用了dict(self)，这会把自定义的SubConfig/Config转成普通字典，彻底丢失ruamel.yaml用来保存格式信息的特殊结构。

解决方案步骤

1. 切换到Round Trip模式

ruamel.yaml提供了typ="rt"（Round Trip）模式，专门用来保留原YAML的所有格式细节，包括注释、键顺序、缩进风格。

2. 继承`CommentedMap`而非普通`dict`

ruamel.yaml用CommentedMap（带注释的有序字典）来存储YAML的映射结构，让你的自定义SubConfig和Config类继承它，才能保留格式信息。

3. 调整dump逻辑

不要将自定义字典转成普通dict，直接dump实例本身，同时正确配置缩进参数。

修改后的完整代码

#!/usr/bin/env python3
import sys
import os
from pathlib import Path
import ruamel.yaml
from ruamel.yaml.comments import CommentedMap

class SubConfig(CommentedMap):
    def __init__(self, parent):
        super().__init__()
        self.parent = parent

    def updated(self):
        self.parent.updated()

    def __setitem__(self, key, value):
        if isinstance(value, dict) and not isinstance(value, CommentedMap):
            v = SubConfig(self)
            v.update(value)
            value = v
        super().__setitem__(key, value)
        self.updated()

    def __getitem__(self, key):
        try:
            res = super().__getitem__(key)
        except KeyError:
            # 新增的键用SubConfig，确保后续修改能触发更新
            super().__setitem__(key, SubConfig(self))
            self.updated()
            return super().__getitem__(key)
        return res

    def __delitem__(self, key):
        res = super().__delitem__(key)
        self.updated()

    def update(self, *args, **kw):
        # 用CommentedMap的update逻辑，保留原有注释和顺序
        for arg in args:
            if isinstance(arg, CommentedMap):
                # 合并时保留原注释
                self.merge(arg)
            else:
                for k, v in arg.items():
                    self[k] = v
        for k, v in kw.items():
            self[k] = v
        self.updated()

# 让SubConfig能被正确序列化
_SR = ruamel.yaml.representer.RoundTripRepresenter
_SR.add_representer(SubConfig, _SR.represent_dict)

class Config(CommentedMap):
    def __init__(self, filename, auto_dump=True):
        super().__init__()
        self.filename = filename if hasattr(filename, "open") else Path(filename)
        self.auto_dump = auto_dump
        self.changed = False
        # 切换到Round Trip模式
        self.yaml = ruamel.yaml.YAML(typ="rt")
        # 配置缩进，匹配原文件的4空格映射缩进
        self.yaml.indent(mapping=4, sequence=4, offset=2)
        self.yaml.default_flow_style = False
        if self.filename.exists():
            with open(filename, 'r') as f:
                # 加载得到CommentedMap，直接合并到self
                loaded_data = self.yaml.load(f) or CommentedMap()
                self.merge(loaded_data)

    def updated(self):
        if self.auto_dump:
            self.dump(force=True)
        else:
            self.changed = True

    def dump(self, force=False):
        if not self.changed and not force:
            return
        with open(self.filename, "w") as f:
            # 直接dump self，不要转成普通dict
            self.yaml.dump(self, f)
        self.changed = False

    def __setitem__(self, key, value):
        if isinstance(value, dict) and not isinstance(value, CommentedMap):
            v = SubConfig(self)
            v.update(value)
            value = v
        super().__setitem__(key, value)
        self.updated()

    def __getitem__(self, key):
        try:
            res = super().__getitem__(key)
        except KeyError:
            super().__setitem__(key, SubConfig(self))
            self.updated()
            return super().__getitem__(key)
        return res

    def __delitem__(self, key):
        res = super().__delitem__(key)
        self.updated()

    def update(self, *args, **kw):
        for arg in args:
            if isinstance(arg, CommentedMap):
                self.merge(arg)
            else:
                for k, v in arg.items():
                    self[k] = v
        for k, v in kw.items():
            self[k] = v
        self.updated()

# 测试示例
cfg = Config(Path("config.yaml"))
# 修改某个值，比如cfg['c']['b']['f'] = 10
# 执行后config.yaml会保留原注释、键顺序和缩进