GridFSBucket比GridFS更推荐，但必须传db实例而非client；需显式设置chunk_size_bytes、metadata（含content_type）和filename；下载须用open_download_stream()分块读取；查文件优先用_id并建索引。
GridFSBucket比GridFS更推荐，但必须传db实例而非client
PyMongo 4.x 中 GridFS 类已明确标记为 legacy，官方文档建议优先用 GridFSBucket。它不是简单替换，而是接口设计逻辑完全不同：你必须显式传入 database 实例（比如 db = client["mydb"]），不能只传 MongoClient 对象。否则会报 AttributeError: 'MongoClient' object has no attribute 'fs' 或静默失败。
常见错误现象：
- 用
GridFSBucket(client, bucket_name="images")—— 直接报错 - 漏写
bucket_name参数，结果文件全进默认的fs桶，和旧版冲突
正确写法示例：
from pymongo import MongoClient
from gridfs import GridFSBucket
<p>client = MongoClient("mongodb://localhost:27017")
db = client["filestore"] # ← 必须是 database 实例
bucket = GridFSBucket(db, bucket_name="images")
上传时必须手动控制 chunk_size_bytes 和 metadata
默认 chunk_size_bytes=255 * 1024（255KB）对小图或文本极不友好：64KB 的 PNG 被切成 2 块，浪费空间且增加 chunks 文档数；而 50MB 视频则生成近 200 个 chunk 文档，拖慢查询和恢复速度。metadata 若不设 content_type，前端无法识别 MIME 类型，图片显示为下载、视频无法自动播放。
上传前要处理的三个硬性参数：
-
chunk_size_bytes：按典型文件大小调，如小图用64 * 1024，大视频用1024 * 1024 -
metadata字典中至少含"content_type"（如"image/png"），其他字段如"uploaded_at"、"original_size"可选但强烈建议 -
filename必须用os.path.basename(path)提取，避免路径注入（如"../etc/passwd"）
流式下载必须用 open_download_stream()，禁用 get() 或 read()
对 >10MB 的文件，调用 bucket.open_download_stream(file_id) 后若直接 .read()，PyMongo 会把全部 chunks 拼成一个 BytesIO 对象——内存瞬间暴涨，服务可能 OOM。这不是 bug，是设计使然：GridFSBucket 的流接口是单次消费、不可 seek 的迭代器，必须分块读。
安全读取方式：
- Web 响应场景：用
Response(stream_with_context(generate()), mimetype=...)，其中generate()函数内循环stream.read(65536)并yield - 本地保存场景：用
with open(..., "wb") as f:配合while True:+chunk = stream.read(8192) - 绝对不要：
data = stream.read()、bucket.get(file_id).read()、bucket.get_last_version(filename).read()
注意：open_download_stream() 返回对象不支持 seek() 或重复调用 read()，用完即失效。
查文件别依赖 filename，优先用 _id + 索引优化
filename 在 GridFS 中不是唯一键，也不做校验，同名文件可多次上传（默认覆盖），且文件名含 Unicode 或特殊字符时易出编码问题。生产环境查文件必须用 _id——它是 ObjectId，唯一、高效、无歧义。
如果非要用 filename 查，务必提前建索引，否则 find_one({"filename": "a.jpg"}) 是全表扫描：
- 执行
db.fs.files.create_index("filename")（注意是fs.files，不是fs.chunks） - 若按元数据查（如
{"metadata.type": "pdf"}），建复合索引：db.fs.files.create_index({"metadata.type": 1, "metadata.year": -1}) - 别在
chunks集合上建任何索引——它只存二进制块，没业务字段
真正容易被忽略的是：bucket.find() 返回的是 Cursor，不是 list；遍历时若未消费完就丢弃，连接池里可能残留游标，长期运行后触发 MaxTimeMSExpired 错误。
