Python使用StreamingResponse返回大文件的写法

Python中使用StreamingResponse流式返回大文件（如视频）需规避内存溢出和响应头延迟问题，关键在于用生成器分块读取（推荐8192字节）、显式设置media_type、添加Accept-Ranges和Content-Range头以支持拖拽播放；若未处理Range请求头，浏览器将无法跳播甚至报错；而对纯静态文件场景，FileResponse凭借零拷贝和自动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 可能静音或无法拖动。

为什么用 FileResponse 而不是 StreamingResponse 更稳妥

如果你只是想「快速返回静态大文件」，FileResponse 是更优解：它底层调用操作系统 sendfile（Linux/macOS）或 TransmitFile（Windows），零拷贝、不占 Python 内存、自动处理 Range 和 If-Modified-Since。

• FileResponse 不走 Python 迭代器，没有 GIL 阻塞问题
• 不支持自定义处理逻辑（如权限校验后动态拼接视频），这时才必须上 StreamingResponse
• 用 StreamingResponse 时，别忘了加超时控制——万一文件被删或磁盘挂了，生成器卡死，连接就永远 hang 住

真正难的不是写流，是边界情况：文件并发修改、磁盘满、客户端突然断连、Range 头格式错误……这些都得在生成器里 try/except 并主动 close 文件句柄。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python使用StreamingResponse返回大文件的写法》文章吧，也可关注golang学习网公众号了解相关技术文章。