gridfsbucket是官方推荐的现代api，gridfs已被弃用；前者仅管理“桶”，不封装文件名去重等语义，所有操作更显式可控，需手动处理唯一性、索引和版本逻辑。
GridFSBucket 和 GridFS 的核心区别在哪
GridFS 类在 PyMongo 4.0+ 中已被标记为弃用，官方明确推荐迁移到 GridFSBucket。关键不是“换个类名”，而是设计模型变了：GridFS 把文件元数据和分块数据全包在一个类里，而 GridFSBucket 更贴近底层存储逻辑——它只管“桶”（bucket），不自动处理文件名冲突、版本覆盖等语义，所有行为更显式、更可控。
这意味着你不能再依赖 put() 自动按文件名去重或覆盖旧版本；也不能再用 get_last_version() 这种带业务逻辑的封装方法。
如何用 GridFSBucket 替换常见的 GridFS 操作
迁移不是一对一替换，得按实际用途重写逻辑：
-
上传文件：用
upload_from_stream(filename, data)，注意filename只是元数据字段，不保证唯一性；如需防止重复，得自己查find({"filename": "xxx"})或加metadata字段配合索引 -
下载文件：用
open_download_stream_by_name(filename)获取流，或用open_download_stream(file_id)精确匹配；by_name默认返回最新插入的（按_id时间顺序），不是按上传时间或版本号 -
删除文件：用
delete(file_id)，不能直接删 filename —— 因为同名可能有多个，必须先查出file_id -
获取文件信息：用
find({"filename": "xxx"})查fs.files集合，或用list()列出所有 filename（但不包含 _id 或 uploadDate）
示例：上传并确保不重复
from pymongo import MongoClient
from gridfs import GridFSBucket
<p>client = MongoClient()
db = client["mydb"]
bucket = GridFSBucket(db)</p><h1>先检查是否已存在同名文件（按 filename + metadata 标识）</h1><p>existing = list(bucket.find({"filename": "report.pdf", "metadata.env": "prod"}))
if not existing:
with open("report.pdf", "rb") as f:
file_id = bucket.upload_from_stream(
"report.pdf",
f,
metadata={"env": "prod"}
)
</p>
容易踩的坑：filename 不等于唯一标识
这是最常翻车的点。在 GridFS 里，get_last_version("a.txt") 是安全的；但在 GridFSBucket 中，open_download_stream_by_name("a.txt") 只返回按 _id 排序的第一个匹配项——如果并发上传、手动插入了多个同名文件，结果不可预测。
- 别依赖
filename做业务主键，应生成业务 ID 放进metadata，并建复合索引：db.fs.files.create_index([("metadata.order_id", 1)]) -
list()返回的是字符串列表，不含任何时间或版本信息，不能用于判断“最新版” -
upload_from_stream()不校验filename是否已存在，也不会自动覆盖，这点和旧版行为完全不同
性能与兼容性要注意什么
GridFSBucket 底层仍用 fs.chunks 和 fs.files，所以数据格式完全兼容，老 GridFS 写入的数据能被 GridFSBucket 正常读取——但反过来，如果你用 GridFSBucket 上传了带自定义 chunk_size_bytes 的文件，老客户端可能解析失败（因 chunk 大小不一致）。
- 上传大文件时，可传
chunk_size_bytes=256 * 1024控制分块大小，默认 255KB；调小利于内存控制，调大可减少 chunk 文档数量 - PyMongo 4.0+ 才支持
GridFSBucket，3.x 用户必须升级；同时确认 MongoDB 服务端版本 ≥ 3.6（无硬性要求，但低版本缺失部分索引能力） -
open_download_stream_by_name()内部会执行一次find查询，高并发下注意fs.files.filename字段是否建了索引（默认没有）
实际用的时候，复杂点往往不在 API 调用本身，而在怎么定义“一个文件”的业务边界——是靠 filename？还是靠 metadata 组合？或者干脆用独立的业务表来管理文件引用关系。这个决策比换哪个类更重要。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
