必须在uploadfromstream或openuploadstream调用时通过metadata参数一次性写入自定义字段，否则无法落地到fs.files.metadata中；后续update会导致元数据缺失或查询失败，且metadata须为合法json对象、不支持根层级直接写字段。
uploadFromStream 的 metadata 参数必须显式传入
GridFS 不支持“先存文件再补元数据”，所有自定义字段必须在 uploadFromStream 或 openUploadStream 调用时，通过 metadata 选项一次性写入。漏掉这个参数，fs.files 文档里就只有 filename、length、uploadDate 等默认字段，查不到你想要的 author 或 project_id。
-
metadata必须是 plain object（Node.js）、dict（PyMongo）、或显式调用SetMetadata()（Go），不能是字符串、数组或null - 别把
contentType塞进metadata——它是独立参数，和metadata同级，例如：{contentType: "image/jpeg", metadata: {tags: ["public"]}} - PyMongo 中常见错误：把
metadata当作第 3 个位置参数传，结果被当成chunk_size_bytes，报错TypeError: 'dict' object cannot be interpreted as an integer
metadata 字段是唯一安全的嵌套入口
自定义字段必须落在 fs.files.metadata 这个嵌套对象下，不是文档根层级。MongoDB 7.0+ 官方驱动强制校验结构，手动往根层级写 author、version 会导致插入失败，或后续 openDownloadStream() 找不到文件。
- ✅ 正确：
{"metadata": {"author": "alice", "tags": ["draft"]}} - ❌ 错误：
{"author": "alice", "filename": "x.pdf"}（绕过驱动，破坏 GridFS 协议） - 避免用
_private这类以下划线开头的键名，部分工具链会过滤掉 - 时间/枚举等非 BSON 原生类型必须手动序列化：如
LocalDateTime→"2026-07-09T14:30:00"，直接传对象会存成null或乱码
查询时路径要带 metadata. 前缀
查自定义字段时，字段路径必须写成 metadata.author，不是 author。因为数据实际存在 fs.files.metadata.author，不是 fs.files.author。
- 查作者为
"bob"的文件：db.fs.files.find({"metadata.author": "bob"}) - 组合条件（PDF + 某标签）：
db.fs.files.find({"metadata.tags": "pdf", "filename": {"$regex": "\.pdf$"}}) - 如果查询频繁，记得建索引：
db.fs.files.createIndex({"metadata.project_id": 1, "uploadDate": -1}) - 别在
fs.chunks上查这些字段——它们只存在于fs.files
字段名和类型一致性容易被忽略
字段名冲突或类型不一致，上线后才会暴露问题，修复成本高。
- 避开 GridFS 保留键：
_id、filename、chunkSize、md5、uploadDate—— 写进去可能破坏块逻辑或下载行为 - 建议所有自定义字段加前缀，比如
app_owner_id、ext_status - 类型必须稳定：
version不能一会儿是string（"1.2"），一会儿是number（1），否则find({"metadata.version": {$gt: 1}})会漏数据 - 数组值（如
tags: ["pdf", "internal"]）可用$in查询，但没索引的话，大集合下就是全表扫
metadata 当成可选装饰项，或者误以为能事后补——它其实是 GridFS 文件创建流程中不可跳过的契约字段。
