YAML-CPP的YAML::Node是引用语义句柄，直接赋值会丢失原节点类型、子节点、注释及锚点；修改嵌套结构需逐级检查存在性与类型；Sequence索引赋值不自动扩容，须先校验或手动扩展；注释和锚点无法通过常规赋值保留。
直接用 = 赋值会清空原节点类型和内容
YAML-CPP 的 YAML::Node 不是“值语义”容器，而是引用语义的句柄。对一个已有节点执行 node = "new_value"，不是修改其内容，而是让该句柄指向一个全新构造的字符串节点——原节点的类型（比如 Map 或 Sequence）、子节点、注释、锚点等全部丢失。
- 错误写法：
root["config"]["timeout"] = 30;—— 如果root["config"]["timeout"]原本是Map或带注释的节点，这行代码会让它变成纯数字节点，且父节点结构不受影响但子树被替换 - 正确思路：先确保路径存在且为可赋值类型，再用
operator[]或operator()定位到目标位置后赋值 - 若目标键不存在，
operator[]会自动创建（类型为Null），再赋值才安全；若已存在但类型不兼容（如想把Map当标量赋值），运行时抛异常YAML::InvalidNode
修改嵌套 Map 中的字段必须逐级确认存在性
YAML-CPP 不支持类似 JSON Pointer 的路径一次性访问，所有中间层级都需显式展开。直接链式调用 root["a"]["b"]["c"] = 42 在任意一级为空时会静默创建 Null 节点，但后续赋值可能失败或行为异常（例如对 Null 调用 operator[] 是合法的，但对其赋值仍受限于上下文）。
- 推荐做法：用
IsDefined()检查关键路径是否存在，或用operator[]逐层获取并验证类型 - 安全写法示例：
auto& config = root["config"]; if (!config.IsMap()) { config = YAML::Node(YAML::NodeType::Map); // 强制转为 Map } config["timeout"] = 30; - 注意：
root["config"]["timeout"]返回的是临时YAML::Node，不能对其取地址或长期持有；若需多次操作，务必用auto&引用绑定
给 Sequence 元素赋值要避免越界或类型错配
YAML-CPP 的 Sequence 类似 vector，但索引访问不自动扩容。seq[5] = "x" 若 seq 长度 ≤ 5，不会扩展长度，而是触发未定义行为或抛出 YAML::BadSubscript（取决于编译选项和版本）。
- 向末尾追加：用
seq.push_back(value)，安全可靠 - 修改指定索引：先用
seq.size()判断是否越界，再用seq[index]赋值；若需扩容，手动循环push_back(YAML::Null)直到满足长度 - 常见坑：
seq[0]["name"] = "test"—— 若seq[0]是标量（如字符串），此操作会崩溃；必须先确保seq[0]是Map类型，可用seq[0].reset(); seq[0] = YAML::Node(YAML::NodeType::Map);
保留注释和锚点？别指望 = 运算符
YAML-CPP 1.x 系列（最常用版本）的 operator= 和 operator[] 完全不处理注释、锚名、标签等元信息。所有赋值操作都会丢弃这些内容，这是设计使然，不是 bug。
立即学习“C++免费学习笔记（深入）”；
- 如果必须保留格式细节，只能用底层 API（如
YAML::Emitter手动拼接）或切换到支持完整 YAML 1.2 语义的库（如 libyaml + 自定义解析器） - 实际项目中更可行的折中：将配置拆为“结构模板”（含注释/锚点的原始 YAML 文件）和“数据层”（用
YAML::Node动态加载/修改的纯数据），运行时合并生成最终输出 - 一个容易被忽略的细节：
YAML::LoadFile()读入的节点默认不保留注释，即使源文件有；只有通过YAML::Parser+YAML::Directives手动解析才能拿到注释 token，但无法用标准 Node API 写回去
