pyyaml 默认不保留注释，因解析时将注释视为无关 token 跳过；如需保留注释，应使用 ruamel.yaml，它专为可编辑 yaml 设计，支持原样保留注释、缩进及引号风格。
直接用 PyYAML 会丢掉注释，这是默认行为
PyYAML 的 yaml.load() 和 yaml.dump() 默认不保留注释——因为标准解析流程会把注释当作无关 token 直接跳过。你读进来再写出去，所有 # 行都会消失。这不是 bug，是设计使然。
如果必须保留注释（比如运维配置、CI/CD 模板、用户可编辑的 config.yaml），得换用支持「注释感知」的解析器：
-
ruamel.yaml是目前最成熟的选择，专为「可编辑 YAML」设计，能原样保留注释、缩进、引号风格 - 别用
pyyaml 配合自定义 Loader——它不提供注释 API，强行 hack 容易崩溃 -
ruamel.yaml不兼容PyYAML的部分接口（比如safe_load替换为load），迁移时注意类型检查
用 ruamel.yaml 读取并修改带注释的 YAML
核心是用 RoundTripLoader 和 RoundTripDumper，它们让 YAML 节点记住位置和注释信息：
from ruamel.yaml import YAML
from ruamel.yaml.comments import CommentedMap
<p>yaml = YAML()
yaml.preserve_quotes = True # 保持原有引号
yaml.indent(mapping=2, sequence=4, offset=2)</p><p>with open("config.yaml") as f:
data = yaml.load(f) # 不是 safe_load！</p><h1>修改值（注释仍附着在原 key 上）</h1><p>data["database"]["host"] = "10.0.1.5"
data["debug"] = True</p><h1>添加新字段，带行首注释</h1><p>data.yaml_set_comment_before_after_key("timeout", before="### 连接超时（秒）")
data["timeout"] = 30</p><p>with open("config.yaml", "w") as f:
yaml.dump(data, f)</p>
注意：data 是 CommentedMap 或 CommentedSeq，不是普通 dict；直接用 data["key"] = ... 是安全的，但别用 dict.update()——它会抹掉注释元数据。
给特定字段加行内注释或键后注释
ruamel.yaml 把注释分三种：行首（before）、行尾（inline）、键后（after）。常见需求如下：
- 给某个 key 加说明性注释：用
yaml_set_comment_before_after_key("log_level", before="# 日志级别：debug/info/warn/error") - 在值后面加注释（如
port: 8080 # HTTP 端口）：用data["port"].yaml_add_eol_comment("HTTP 端口") - 修改已有 inline 注释：先删再加，
data["port"].ca.items.pop("comment", None)，否则会叠加 - 注释内容里不能含
:或#开头的子串，否则解析可能错位——建议只用 ASCII 简单描述
为什么不用 yaml.load(..., Loader=yaml.CSafeLoader)？
CSafeLoader 是 PyYAML 的 C 实现，快但「太干净」：它不存任何注释、锚点、标签信息，连空行都压缩。即使你传了 RoundTripLoader，只要底层用了 CSafeLoader，注释就注定丢失。
正确做法是显式指定 loader：
from ruamel.yaml import YAML <p>yaml = YAML()</p><h1>✅ 正确：ruamel 自带的 RoundTripLoader</h1><p>data = yaml.load(stream)</p><h1>❌ 错误：混用 PyYAML 的 Loader</h1><h1>data = yaml.load(stream, Loader=yaml.CSafeLoader)</h1>
另外，ruamel.yaml 从 0.17 开始默认禁用 yaml.load() 的任意代码执行（类似 PyYAML 的 unsafe_load），所以不必额外担心反序列化风险。
注释不是装饰，是配置文件的语义一部分。一旦开始用脚本改 YAML，就必须全程走 ruamel.yaml 的节点对象链——绕开它，等于放弃注释控制权。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
