GridFS是MongoDB基于fs.files和fs.chunks两个集合实现的大文件存储规范，适用于存储>16MB的不可变文件（如视频、备份包），不适用于高频小文件或需CDN、权限隔离的场景。
GridFS 是什么，什么时候该用它
GridFS 不是 MongoDB 的独立功能，而是基于普通集合模拟出来的文件存储层。它把大文件切片存进 fs.chunks 和 fs.files 两个集合，适合存 >16MB 的文件（比如视频、备份包、日志归档），但不适合高频小文件（如用户头像）——那种直接用 Base64 存文档字段更轻量。
常见误判：以为 GridFS 能替代对象存储。它不提供 CDN、权限隔离、生命周期管理，只是“让 MongoDB 能塞得下大文件”。
安装依赖和初始化 GridFS 实例
必须装 pymongo，且版本 ≥4.0（旧版 API 差异大）。gridfs 模块随 pymogo 自动安装，不用单独 pip。
pip install pymongo
连接后不能直接用 db.fs，要显式构造 GridFS 实例：
立即学习“Python免费学习笔记（深入）”；
✅ 正确写法：
from pymongo import MongoClient
import gridfs
<p>client = MongoClient("mongodb://localhost:27017")
db = client["myapp"]
fs = gridfs.GridFS(db) # 注意：不是 db.fs</p>❌ 常见错法：
-
db.fs.put(...)——db.fs是个空属性，会报AttributeError - 用
GridFS(db, collection="myfiles")却忘了所有操作（如find）也得用同名 collection 初始化，否则查不到
上传文件：注意文件对象和元数据处理
fs.put() 接收字节流（bytes 或类文件对象），不接受路径字符串。别直接传 "./video.mp4"，会存下这个字符串本身。
上传示例：
with open("large_video.mp4", "rb") as f:
file_id = fs.put(f, filename="video.mp4", content_type="video/mp4", tags=["raw", "2024"])
关键参数说明：
-
filename：仅用于标识，不影响存储路径（GridFS 无目录结构） -
content_type：纯 metadata，下载时需手动读取，MongoDB 不校验格式 -
tags：列表类型，方便后续find({"tags": "raw"})查询 - 返回值
file_id是ObjectId，务必保存——它是唯一检索凭证
下载文件：别漏掉 close()，小心内存爆炸
fs.get() 返回一个类似文件对象的 GridOut 实例，支持 read()、readlines()，但不会自动关闭底层游标。
安全下载方式：
grid_out = fs.get(file_id)
with open("downloaded.mp4", "wb") as f:
f.write(grid_out.read()) # 或用 chunked read 避免 OOM
grid_out.close() # 必须调用！否则连接池泄漏
大文件要分块读（尤其服务端）：
grid_out = fs.get(file_id)
with open("out.bin", "wb") as f:
while True:
chunk = grid_out.read(1024 * 1024) # 每次读 1MB
if not chunk:
break
f.write(chunk)
grid_out.close()
容易踩的坑：
- 用
fs.find_one({"filename": "x"})查到的是GridOut对象，不是原始 bytes；想转 bytes 得调.read() -
fs.delete(file_id)成功后，对应fs.files文档被删，但fs.chunks可能残留（极少发生，但测试环境建议手动清） - 并发上传同名文件？GridFS 允许多个同名文件共存，靠
_id区分，filename不唯一
GridFS 的 chunk 大小默认 255KB，改它要初始化时传 chunk_size_bytes，但改了就得全库统一，混用会导致读取错乱——这点常被忽略。
