用 BsonSerializer
序列化对象到 BSON 文件
直接调用
BsonSerializer是最可控的方式，尤其当你需要精确控制字段序列化行为（比如忽略 null、自定义日期格式）时。它不依赖 MongoDB 服务，纯内存操作，适合离线生成 BSON 文件。
常见错误是传入
null对象或未标记可序列化的类——
BsonSerializer会直接抛
ArgumentException或
InvalidOperationException。 确保目标类有无参构造函数，或显式注册自定义序列化器 用
BsonSerializer.Serialize<t>(stream, obj)</t>，别漏掉
stream.Position = 0（如果复用流） 写入前建议用
using var fs = new FileStream(path, FileMode.Create)，避免文件句柄残留 注意：
BsonSerializer默认不处理
Dictionary<string object></string>的深层嵌套类型，遇到
object值可能报
NotSupportedException
var person = new { Name = "Alice", Age = 30 };
using var fs = new FileStream("data.bson", FileMode.Create);
BsonSerializer.Serialize(fs, person);用 MongoDB.Bson
的 BsonDocument
构建再写入
如果你的数据结构动态性强（比如来自 JSON 配置、API 响应），用
BsonDocument手动组装比反射序列化更稳妥，也更容易调试字段名和类型是否符合预期。
容易踩的坑是误用
BsonValue.Create()处理
DateTime或
ObjectId：它不会自动转成 BSON 原生类型，而是包成
BsonString，导致后续读取时类型丢失。 优先用
new BsonDocument { { "name", "Alice" }, { "ts", DateTime.UtcNow } } 这种字面量方式
时间字段务必传 DateTime实例，不要先 ToString() 写入文件前，用
doc.ToBson()得到
byte[]，再写入文件，比直接序列化
BsonDocument更少歧义 注意：
BsonDocument不支持循环引用，尝试添加自身会触发
StackOverflowException
var doc = new BsonDocument { { "name", "Bob" }, { "score", 95.5 } };
File.WriteAllBytes("doc.bson", doc.ToBson());反序列化时字段名大小写/缺失字段怎么处理
从 BSON 文件读回来时，
BsonSerializer.Deserialize<t></t>默认严格匹配字段名（区分大小写），且要求所有非 nullable 字段在 BSON 中存在。一旦不匹配，就抛
FormatException或静默跳过字段（取决于配置）。
这不是 bug，是 BSON 规范的严谨性体现。但实际中常因导出工具、跨语言协作导致字段名小写、下划线分隔或字段缺失。
加[BsonElement("user_name")] 显式绑定字段，比依赖命名约定更可靠
对可选字段，用 int?、
string（而非
string!）并配合
[BsonDefaultValue(null)]全局关闭大小写敏感：注册时传
new JsonSerializerOptions { PropertyNamingPolicy = null }（仅限 .NET 6+ + System.Text.Json互操作场景） 读取未知结构用
BsonDocument.Parse(File.ReadAllText("x.bson"))（⚠️仅限 UTF-8 编码的 BSON 文本，不是二进制 BSON 文件）
文件头、多文档、流式写入要注意什么
BSON 文件本身没有标准“文件头”。单个 BSON 文档就是一串连续字节；多个文档拼接时，必须手动处理长度前缀或分隔符，否则读取端无法知道哪里是一条记录的结束。
很多人以为直接把几个
BsonDocument.ToBson()结果
Concat起来就能当“BSON 文件”用，结果用
mongodump或其他工具打不开——因为那只是字节拼接，不是合法的 BSON stream 格式。 若需存多文档，推荐每条前面写 4 字节长度（小端序），即 BSON spec 定义的
document length，这是最通用的兼容做法 不要用
StreamWriter写 BSON 二进制内容，会导致编码污染（如 UTF-8 BOM） 大文件写入时，避免一次性
ToBson()全部加载内存，改用
BsonBinaryWriter流式写入 确认文件是否真为 BSON：用十六进制编辑器看开头是否为
13 00 00 00（一个长度为 19 的最小文档）
C# 操作 BSON 文件的关键不在“能不能写”，而在于你是否清楚自己写的是「单文档二进制块」还是「多文档流协议」——后者没有现成封装，得自己按 spec 补长度头。很多问题其实卡在这一步。
