GridFS适合存储大于16MB的大型文件，如视频片段、原始日志包、模型权重文件（.pt/.bin）、备份SQL导出文件；不适用于几MB以内的小文件，此时应直接用BinData。
GridFS 适合存什么文件
GridFS 不是为任意文件设计的，它解决的是「单文档超 16MB」这个硬限制。如果你的文件稳定在几 MB 以内，直接用 BinData 存进普通字段更简单、查询更快。GridFS 真正该用的场景是：视频片段、原始日志包、模型权重文件（.pt/.bin）、备份 SQL 导出文件——这些动辄几十 MB 到几 GB，且你不需要高频随机读某一段字节，而是整存整取。
常见错误现象：writeConcern failed: { wtimeout: true } 或上传中途断连后文件残缺，往往是因为误把小文件塞进 GridFS，又没配好连接池和超时。
- 文件大于 16MB 才考虑 GridFS
- 需要按文件名/元数据检索，而非按内容字段查
- 不依赖原子性跨分片更新（GridFS 的
chunks和files集合不在同一事务中）
用 mongofiles 命令行快速验证流程
别急着写代码，先用官方工具跑通端到端：上传 → 查看 → 下载。这能绕过驱动层封装，直击底层行为，排查权限、网络、分片配置问题最有效。
使用场景：CI 流程中做基础连通性检查；临时迁移一批大文件；确认副本集是否允许写入 fs.chunks。
-
mongofiles --host rs0/localhost:27017 --db myapp -r put ./report.pdf（-r覆盖同名文件） -
mongofiles --db myapp list查看是否生成两条记录（files+chunks） - 如果报错
not authorized on myapp to execute command { listFiles: 1 }，说明用户缺少read角色对fs.files - 默认 chunk 大小是 255KB，可通过
--chunkSizeBytes 524288改成 512KB，减少 chunk 文档数，但会提高内存压力
Node.js 驱动里 GridFSBucket 的关键参数陷阱
用 mongodb npm 包时，GridFSBucket 构造函数看着简单，但三个参数稍有偏差就会导致文件写进错库、或无法被其他服务读到。
参数差异直接影响生产环境多租户隔离能力：
-
bucketName默认是"fs"，但你可以设成"uploads"或"backups"—— 这会创建uploads.files和uploads.chunks两个集合，和默认fs.*完全隔离 -
chunkSizeBytes必须和读取端一致，否则openDownloadStream会解包失败（错误信息类似Corrupted download: chunk size mismatch） - 不要复用同一个
GridFSBucket实例跨数据库操作；每个 DB 应 new 一个新实例，并传入对应db对象 - 上传时传入的
metadata是普通 BSON 对象，但注意字段名别用_id或filename，它们会被 GridFS 自动覆盖
为什么 find 查不到刚上传的文件
不是代码写错了，大概率是忘了 await 或没等写入确认完成。GridFS 写入分两步：先写 files 文档，再并发写 chunks；而 find 查询只查 files 集合，如果 chunks 还没写完，files 里已有记录，但状态不完整。
性能影响：默认 write concern 是 { w: 1 }，即主节点写完就返回，此时从节点可能还没同步，secondary 读会漏掉新文件。
- 上传后必须
await bucket.uploadFromStream(...)完整结束，不能只.then()就去查 - 线上建议设
writeConcern: { w: "majority" }，尤其在分片集群中 - 查文件前加 100ms 等待不是好办法；正确做法是用
bucket.find({ filename: "x.pdf" }).toArray()并检查返回数组长度是否 > 0，再结合uploadDate字段做时间过滤 - 如果用聚合管道查，注意
$lookup关联chunks会很慢，避免在列表页做
