YAML::BeginMap/EndMap 是流式标记，不维护嵌套状态，易因顺序错乱导致解析失败；必须严格按“开map→写key→开子map→…→关子map→关父map”顺序手动配对，否则报“mapping values not allowed in this context”等错误。
直接用 YAML::BeginMap 和 YAML::EndMap 无法生成嵌套结构——它们只是流式写入的标记，不维护层级状态，必须靠缩进/顺序和配对逻辑来保证结构正确，稍有错位就导致解析失败。
为什么 YAML::BeginMap / EndMap 容易写错嵌套
这两个操作符本身不检查嵌套深度，也不自动管理作用域。你调用 YAML::BeginMap 后，后续所有键值对都属于当前 map，直到遇到匹配的 YAML::EndMap；但若中间又嵌套了 map 或 seq，就必须手动确保 EndMap 出现在正确位置，否则 YAML 解析器会报 Invalid mapping structure 或 Expected <block end>, but found <block mapping start></block></block> 这类错误。
- 常见错误：在子 map 未闭合前就写了外层的
YAML::EndMap - 典型现象：生成的 YAML 看似缩进正常，但用
yaml-cpp加载时报YAML::ParserException，提示“mapping values not allowed in this context” - 根本原因：流式 emitter 不保存上下文，全靠开发者手写顺序模拟树形结构
正确构造嵌套 map 的写法（以三层为例）
必须严格按“开 map → 写 key → 开子 map → … → 关子 map → 关父 map”顺序推进，不能跳步或交叉。下面是一个生成如下结构的可靠写法：
server:
host: "localhost"
ports:
- 8080
- 8443
features:
auth: true
cors: false对应 C++ 代码：
立即学习“C++免费学习笔记（深入）”；
YAML::Emitter out; out << YAML::BeginMap; out << YAML::Key << "server"; out << YAML::Value << YAML::BeginMap; // server map 开始 out << YAML::Key << "host"; out << YAML::Value << "localhost"; out << YAML::Key << "ports"; out << YAML::Value << YAML::BeginSeq; out << 8080; out << 8443; out << YAML::EndSeq; // ports seq 结束 out << YAML::Key << "features"; out << YAML::Value << YAML::BeginMap; // features map 开始 out << YAML::Key << "auth"; out << YAML::Value << true; out << YAML::Key << "cors"; out << YAML::Value << false; out << YAML::EndMap; // features map 结束 out << YAML::EndMap; // server map 结束 out << YAML::EndMap; // 根 map 结束（此处可省，因根即 map）
注意最后那个 YAML::EndMap：如果整个文档就是这个 map，它其实是冗余的；但若后续还要追加其他顶层字段（比如再写一个 database:），就必须保留最外层的 BeginMap/EndMap 包裹。
用 YAML::Node 替代流式写法更安全
如果你需要动态构建复杂嵌套、或逻辑分支多（比如某些字段只在条件满足时才写入），强烈建议放弃纯 Emitter 流式写法，改用 YAML::Node 构建内存树，再一次性 dump：
-
YAML::Node自动管理层级和类型，支持node["a"]["b"]["c"] = 42这种链式赋值 - 支持
node.IsMap()/node.IsSequence()运行时校验，避免类型错配 - 无需手动配对
Begin/End，自然规避缩进错位问题 - 性能差异在千级节点以下基本可忽略；只有在高频实时日志等极端场景才需抠 emitter 性能
示例：
YAML::Node root; root["server"]["host"] = "localhost"; root["server"]["ports"].push_back(8080); root["server"]["ports"].push_back(8443); root["server"]["features"]["auth"] = true; root["server"]["features"]["cors"] = false; std::cout << root;
容易被忽略的细节：缩进、换行与转义
yaml-cpp 默认使用 2 空格缩进且无尾部空格，但如果你手动拼接字符串或混用 Emitter 与原始字符串，可能破坏格式。更隐蔽的问题是：
- 中文或特殊字符（如
路径: /usr/local/bin）会被自动加引号，但若含换行符或冒号后紧跟空格，可能触发非预期的 block style -
YAML::Emitter对std::string默认使用 flow style（单行），对std::vector默认用 block style（多行）——风格不一致会让人工阅读困难 - 调试时别只看
out.c_str()输出，一定要用YAML::Load()再解析一遍，验证是否真正可逆
真正麻烦的从来不是怎么写出合法 YAML，而是写出**人类可读、机器可解析、后续可维护**的 YAML —— 这要求你在 BeginMap 前想清楚层级，在 EndMap 前确认所有子结构已收口，且每个 Key 后紧跟 Value，中间不能插无关语句。
