GridFS元数据存于fs.files集合中，与filename、length等字段同级；自定义字段需直接写入该文档根层级，不可使用metadata字段，且须避开_id、chunkSize等保留键。
GridFS 元数据存哪？不是 metadata 字段
GridFS 没有叫 metadata 的字段。常见误解是以为能直接往某个叫 metadata 的顶层键里塞 KV，实际根本不存在这个字段。所有自定义元数据都必须写进 fs.files 集合中对应文档的根级别——也就是和 filename、length、uploadDate 平级的位置。
用驱动写元数据：别漏掉 SetMeta 或等效方法
不同语言驱动暴露方式不同，但核心逻辑一致：在打开写入流前，把自定义字段挂到文件对象上。
- Go（mgo）：调用
file.SetMeta(bson.M{"author": "Alice", "version": 2})，之后再Write() - Python（pymongo）：传
metadata={"project": "alpha", "tags": ["draft", "v1"]}到bucket.upload_from_stream() - Node.js（mongodb driver）：在
uploadStream上设metadata属性，如stream.metadata = {source: "web", priority: "high"}
漏掉这步，元数据就完全不会写入 fs.files 文档——查 db.fs.files.find() 时只会看到默认字段。
查询带自定义元数据的文件：直接在 fs.files 上查
元数据字段和内置字段一样可被查询，不需要特殊语法或前缀。
- 想查作者为
"Bob"的所有文件：db.fs.files.find({"author": "Bob"}) - 带条件组合：
db.fs.files.find({"category": "log", "uploadDate": {"$gt": ISODate("2026-04-01")}}) - 注意：不能在
fs.chunks上查这些字段——它们只存在于fs.files
如果元数据值是数组（如 tags: ["pdf", "internal"]），可用 $in 或 $all 查询，但记得索引——否则大集合下会全表扫。
元数据字段名冲突风险：避开 GridFS 保留键
GridFS 自己用的字段名包括 _id、filename、length、chunkSize、uploadDate、md5、contentType 等。如果你硬写一个 chunkSize: 1024 进去，可能覆盖默认行为，导致下载失败或块大小错乱。
- 安全做法：所有自定义字段用明确前缀，比如
app_user_id、ext_category - 避免重名：不覆盖
filename，不碰md5，不改uploadDate的类型（它必须是 Date） - 值类型要稳：MongoDB 不允许在同一个字段存 string 和 number，所以
version要么始终是 number，要么始终是 string
最易忽略的是字段类型一致性——上线后某次上传用了 {"version": "1.2"}，另一次用了 {"version": 1}，后续按数字查就会漏掉字符串版本。
