MongoDB单文档BSON大小上限为16MB，超限立即报DocumentTooLarge错误；常见诱因包括日志列表、Base64图片等大字段直塞，或$push致数组越界；GridFS通过分块存储（默认255KB/chunk）替代大文档，需规范使用bucket、metadata及复用实例。
为什么插入文档时突然报 DocumentTooLarge 错误
不是数据量大就一定触发，而是单个 BSON 文档序列化后超过 16MB 立刻失败。这个限制是 MongoDB 服务端硬编码的，客户端连重试都没意义——insertOne 或 updateOne 直接抛错，错误信息里明确带 DocumentTooLarge 字样。
常见诱因：把日志列表、原始图片 Base64、完整 HTML 片段、嵌套过深的分析结果直接塞进一个文档；或者用 $push 不断追加数组，某次操作让总大小跨过 16MB 边界。
- 注意：16MB 是 BSON 编码后的字节长度，不是 JSON 字符串长度（BSON 包含类型标记和长度前缀，通常比等效 JSON 大 5–10%）
- 聚合管道里的
$group或$lookup如果中间结果超限，会报errmsg: "Exceeded memory limit for $group..."，这不是同个限制，但常被混淆 - GridFS 不是“绕过”限制，而是设计来替代大文档存储的方案——它把文件切块存为多个
chunks文档，每个 chunk 默认 255KB，远低于 16MB
用 GridFS 存二进制或大文本的实操要点
别手写分片逻辑，直接用官方驱动内置的 GridFS API。关键不是“怎么存”，而是“怎么选桶名、怎么设选项、怎么避免查不到”。
-
bucketName默认是fs，但建议显式指定，比如logs或uploads，方便权限隔离和清理 - 写入时传
metadata对象，把业务字段（如userId、createdAt）放进去，后续能用find({ "metadata.userId": "abc" })查，比靠filename可靠 - 读取时别只调
openDownloadStream就完事，记得监听error事件——文件不存在时不会抛异常，而是触发 error 回调，内容是"FileNotFound" - Node.js 驱动中，
GridFSBucket实例必须复用，不要每次操作都 new 一个，否则连接池和缓存失效
示例片段（Node.js）：
const bucket = new GridFSBucket(db, { bucketName: 'reports' });
const uploadStream = bucket.openUploadStream('2024-q3-analysis.json', {
metadata: { userId: 'u_789', version: 2 }
});
writeStream.pipe(uploadStream);
拆分文档结构时最容易忽略的关联一致性
把一个大文档拆成主表 + 子集合（比如 orders + order_items），看似简单，但业务查询一多，就会暴露两个坑：应用层 join 效率低、事务边界模糊。
- MongoDB 6.0+ 支持跨集合事务，但要求所有集合在同一个数据库内，且不能含分片集合；如果用了分片集群，
transaction会直接报"Transactions are not supported on sharded clusters" - 用
$lookup做聚合时，子集合数据量大或没建对索引，响应时间会从毫秒跳到几秒——必须确保localField和foreignField都有单字段索引 - 删除主文档时，别依赖应用层手动删子文档；可以用 Change Streams 监听
delete事件触发异步清理，或者用数据库触发器（MongoDB 7.0+ Atlas 支持）
验证是否真踩到 16MB 边界的方法
别靠估算，用驱动自带工具测真实 BSON 大小。不同语言 API 不同，但核心都是序列化后取 .length。
- Node.js：
BSON.serialize(doc).length（需require('bson')） - Python：
len(bson.BSON.encode(doc)) - Shell 中没法直接算，但可以用
Object.bsonsize()（仅 4.4+，且只支持当前 shell 上下文对象，不能查 DB 里已存文档） - 注意：
Object.bsonsize()返回的是近似值，不包含 _id 字段的 ObjectId 开销（实际还多 12 字节），线上排查建议以驱动侧计算为准
如果发现某个文档接近 15.8MB，别想着“再加一点也没事”——BSON 编码过程可能因字段顺序、空值处理产生微小波动，留至少 200KB 余量才稳妥。
