StreamingResponse不能直接返回大文件，因其默认读完迭代器才发响应头，导致无法设置Content-Length且内存溢出；须用生成器分块读取、设media_type、加Accept-Ranges和Content-Range支持拖拽。
StreamingResponse 为什么不能直接返回大文件
因为 StreamingResponse 默认把整个迭代器内容读完才发响应头，而大文件（比如视频）没发完 Content-Length 就没法设，浏览器就卡在 loading；更糟的是，如果用 open(file, "rb") 直接传给 StreamingResponse，它会一次性加载全部内容进内存——1GB 视频 ≈ 1GB 内存占用，服务直接 OOM。
- 必须手动控制 chunk 大小，推荐
8192或65536字节 - 必须显式设置
media_type（如"video/mp4"），否则浏览器可能拒绝播放 - 必须加
Content-Range和Accept-Ranges: bytes才支持视频拖拽，否则只能从头播
怎么用 StreamingResponse 正确流式返回视频文件
核心是「按需读、边读边发」，不缓存全量数据。别用 iter_file()（旧版 FastAPI 有，新版已删），改用生成器手动分块读：
def file_stream(filepath: str):
with open(filepath, "rb") as f:
while chunk := f.read(8192):
yield chunk
@app.get("/video")
def stream_video():
return StreamingResponse(
file_stream("/path/to/video.mp4"),
media_type="video/mp4",
headers={"Accept-Ranges": "bytes"},
)
-
filepath必须是绝对路径，相对路径容易因工作目录变化出错 - 不要在生成器里做耗时操作（如日志、DB 查询），会阻塞流
- 若需支持断点续传（如拖进度条），得解析
Range请求头，手动计算偏移并 seek，不是单纯 yield 全文件
Range 请求处理：拖动进度条的关键
浏览器拖进度条时会发带 Range: bytes=1000-2000 的请求，不处理就返回 200 + 全文件，前端会报错或卡住。必须检查 Range 头，返回 206 Partial Content：
- 用
os.path.getsize()获取文件总长 - 解析
Range头，提取 start/end，校验是否越界 - 用
f.seek(start)跳到位置，再按 chunk 读 - 响应头必须含
Content-Range（格式：bytes 1000-2000/100000）和Content-Length（本次返回字节数）
漏掉任意一项，iOS Safari 就拒绝播放，Chrome 可能静音或无法拖动。
立即学习“Python免费学习笔记（深入）”；
为什么用 FileResponse 而不是 StreamingResponse 更稳妥
如果你只是想「快速返回静态大文件」，FileResponse 是更优解：它底层调用操作系统 sendfile（Linux/macOS）或 TransmitFile（Windows），零拷贝、不占 Python 内存、自动处理 Range 和 If-Modified-Since。
-
FileResponse不走 Python 迭代器，没有 GIL 阻塞问题 - 不支持自定义处理逻辑（如权限校验后动态拼接视频），这时才必须上
StreamingResponse - 用
StreamingResponse时，别忘了加超时控制——万一文件被删或磁盘挂了，生成器卡死，连接就永远 hang 住
真正难的不是写流，是边界情况：文件并发修改、磁盘满、客户端突然断连、Range 头格式错误……这些都得在生成器里 try/except 并主动 close 文件句柄。
