不能用FileResponse直接返回GridFS文件，因其仅支持本地路径且会全量加载内存；须用StreamingResponse配合异步生成器与asyncio.to_thread实现流式读取，并设置Content-Length、合理chunk大小及索引优化。
为什么不能用 FileResponse 直接返回 GridFS 文件
GridFS 文件不在本地磁盘，而是在 MongoDB 的 fs.chunks 和 fs.files 集合里，FileResponse 只能读取本地路径，硬传 grid_out._id 或类似值会直接报 FileNotFoundError。更关键的是，即使你绕过路径检查强行注入字节流，FileResponse 仍会尝试一次性加载全部内容到内存——一个 500MB 视频会让进程吃掉同等内存，且无法控制 chunk 大小和流控节奏。
StreamingResponse + 异步生成器：从 GridFS 拉取并实时 yield
必须用异步生成器配合 StreamingResponse，因为 PyMongo 的 open_download_stream() 返回的是同步文件类对象（GridOutChunkIterator），但它内部的 read() 是阻塞调用。若在异步端点里直接调用，会阻塞整个事件循环。正确做法是用 asyncio.to_thread 包裹读取操作。
- 确保 PyMongo 版本 ≥ 4.7（支持异步驱动更好，但 GridFS 本身无原生 async API）
- chunk 大小建议设为
65536（64KB）或1024 * 1024（1MB）：太小增加系统调用开销，太大削弱流式效果 - 必须显式设置
Content-Length响应头，否则浏览器无法显示进度条、无法拖动播放 - 不要在生成器里调用
stream.close()：StreamingResponse自动管理资源，手动 close 可能导致后续 yield 报ValueError: I/O operation on closed file
from fastapi import FastAPI, HTTPException, Response
from fastapi.responses import StreamingResponse
from pymongo import MongoClient
from gridfs import GridFS
import asyncio
<p>app = FastAPI()
client = MongoClient("mongodb://localhost:27017")
db = client["media_db"]
fs = GridFS(db)</p><p>@app.get("/video/{file_id}")
async def stream_gridfs_video(file_id: str):
try:
grid_out = fs.get(file_id)
except Exception:
raise HTTPException(status_code=404, detail="File not found")</p><pre class='brush:php;toolbar:false;'># Content-Length 必须设，否则前端无法拖动
headers = {
"Content-Length": str(grid_out.length),
"Content-Type": grid_out.content_type or "video/mp4",
"Accept-Ranges": "bytes", # 显式声明支持范围请求（虽 StreamingResponse 不自动处理，但前端会看）
}
async def generate():
stream = fs.open_download_stream(file_id)
try:
while True:
# 阻塞 read() 必须进线程池
chunk = await asyncio.to_thread(stream.read, 65536)
if not chunk:
break
yield chunk
finally:
# 这里 close 是安全的，因 stream 已退出循环
await asyncio.to_thread(stream.close)
return StreamingResponse(generate(), headers=headers)客户端能拖动播放？得加 Range 支持，但 StreamingResponse 不原生支持
StreamingResponse 本身不解析 Range 请求头，也不会返回 206 Partial Content。如果你希望用户能拖动进度条、暂停后继续播放，仅靠上述代码不够——它只返回完整 200 响应，浏览器会认为“不支持分段”，禁用拖动条。
- 真正支持 Range 的方案：改用
Response手动构造 206 响应，需解析Range头、计算偏移、从 GridFS 定位 chunk 起始位置（涉及fs.chunks查询和偏移换算） - 轻量替代：前端用
<video></video>标签时，加preload="metadata"并配合服务端返回准确Content-Length，部分浏览器（Chrome）能在无 Range 的情况下启用基础拖动（依赖视频容器是否含 moov header 在前） - 生产推荐：把 GridFS 作为备份/归档层，热视频走对象存储（如 S3 + CloudFront），由 CDN 原生处理 Range 请求；GridFS 仅用于冷数据或元数据强关联场景
性能瓶颈常卡在 MongoDB 连接与 chunk 查询上
GridFS 流式读取不是单次查询，而是按需从 fs.chunks 查多个文档。每个 read(64KB) 可能触发一次或多次 DB 查询，尤其当 chunk 大小不均或网络延迟高时，容易成为瓶颈。
- 确认
fs.chunks.files_id和n字段有复合索引：db.fs.chunks.createIndex({"files_id": 1, "n": 1}) - 避免在高并发下共用一个
GridFS实例：PyMongo 的GridFS不是线程/协程安全的，多 worker 时建议每个请求新建GridFS(db)或复用带连接池的Client - 如果视频访问频繁，考虑加一层内存缓存（如 Redis）缓存前几个 chunk，跳过首段 DB 查询
最易被忽略的一点：GridFS 的 chunk_size 默认是 255KB，但你的流式读取 chunk 设为 64KB，意味着每次 read() 可能跨多个 GridFS chunk，触发多次 DB 查询。要么调大读取 chunk（如设为 256KB），要么在上传时就指定更小的 chunk_size（需权衡上传稳定性和读取效率）。
