YamlDotNet 解析 UTF-8 BOM 导致属性未找到问题的分析与解决

在使用 YamlDotNet 进行 YAML 文档处理时，开发者可能会遇到一个看似奇怪的问题：当通过 YamlStream 转换文档后再进行反序列化时，系统会抛出"Property not found"异常，而直接使用原始文本则能正常工作。本文将深入分析这一问题的根源，并提供解决方案。

问题现象

当开发者使用 YamlStream 处理 YAML 文档时，通常会按照以下流程操作：

1. 将文本加载到 YamlStream 中
2. 对文档进行修改或处理
3. 将处理后的文档保存回文本
4. 使用 IDeserializer 反序列化处理后的文本

然而，在这一过程中，反序列化步骤可能会抛出 YamlDotNet.Core.YamlException 异常，提示"Property 'Prop1' not found on type 'YamlClass'"，尽管原始文本可以正常反序列化。

问题根源

经过深入分析，发现问题出在文本编码的字节顺序标记(BOM)上。当使用 StreamWriter 将处理后的 YAML 文档写入 MemoryStream 时，默认情况下会写入 UTF-8 BOM(字节顺序标记)。这个不可见的BOM字符会导致 YamlDotNet 的反序列化器无法正确识别文档开头的属性名称。

技术细节

UTF-8 BOM 是一个三字节的序列(0xEF, 0xBB, 0xBF)，位于文件开头，用于标识文件的编码格式。虽然它对人类阅读不可见，但会影响解析器的处理：

1. 原始文本直接反序列化时，通常不包含BOM
2. 通过 StreamWriter 处理后，文本开头被添加了BOM
3. 反序列化器将BOM识别为属性名的一部分，导致无法匹配实际属性

解决方案

有几种方法可以解决这个问题：

方案一：禁用BOM写入

在创建 StreamWriter 时，使用不写入BOM的UTF-8编码：

using StreamWriter w = new(ms2, new UTF8Encoding(false), leaveOpen: true);

方案二：手动去除BOM

在获取最终文本后，手动去除开头的BOM：

text2 = Encoding.UTF8.GetString(ms2.ToArray()).TrimStart('\uFEFF');

方案三：使用StringWriter替代

对于纯文本处理，可以使用StringWriter代替StreamWriter，避免编码问题：

using StringWriter sw = new();
new YamlStream(doc0).Save(sw, false);
text2 = sw.ToString();

最佳实践

1. 在处理YAML文档时，始终明确指定编码格式
2. 对于不需要BOM的场景，使用UTF8Encoding(false)
3. 在跨平台或跨系统处理文本时，特别注意编码一致性
4. 考虑在反序列化前对输入进行规范化处理

总结

YAML处理中的编码问题常常容易被忽视，但却可能导致难以排查的错误。通过理解BOM对文本处理的影响，开发者可以避免类似问题，编写出更健壮的YAML处理代码。YamlDotNet作为.NET平台上的优秀YAML库，在使用时需要注意这些细节，才能充分发挥其功能。