FastAPI大文件流式传输教程

本文深入解析了FastAPI在处理大文件（如2GB视频或超大压缩包）时的流式传输与上传实战方案，直击内存溢出、请求体限制、浏览器下载异常等高频痛点：下载端强调摒弃FileResponse，改用StreamingResponse配合自定义分块生成器和精准响应头（如Content-Disposition与media_type），实现零内存缓冲；上传端则彻底绕过UploadFile和form解析，通过Request.stream()直接读取原始字节流，并协同调优Uvicorn、Nginx及Cloudflare的层级限制；更进一步覆盖断点续传所需的Range协议解析、偏移写入与ETag校验等底层细节——揭示了一个关键真相：在大文件场景下，真正的稳定性不来自框架封装，而源于开发者对HTTP流、系统IO和部署链路的深度掌控。

FastAPI里用StreamingResponse传大文件不卡内存

直接返回大文件（比如 2GB 视频）时，别用 FileResponse——它会一次性读进内存，服务容易 OOM。必须走流式，核心是让 FastAPI 不缓冲、不预加载，边读边发。

关键点：自己控制读取 chunk 大小，配合 iter_file 或生成器；响应头要设对，否则浏览器可能不识别为可下载文件。

• StreamingResponse 的 media_type 建议显式设为 "application/octet-stream"，避免 FastAPI 自动猜错 MIME 导致乱码或无法下载
• 用 open(path, "rb") + iter + read 构造生成器，每次只读 8192 字节（太小增加 syscall 开销，太大失去流控意义）
• 务必加 headers={"Content-Disposition": 'attachment; filename="xxx.zip"'}，否则 Safari 可能直接渲染二进制内容

from fastapi import Response
from starlette.responses import StreamingResponse

def iter_file(file_path: str):
    with open(file_path, "rb") as f:
        while chunk := f.read(8192):
            yield chunk

@app.get("/download")
def download_file():
    return StreamingResponse(
        iter_file("/tmp/large.zip"),
        media_type="application/octet-stream",
        headers={"Content-Disposition": 'attachment; filename="large.zip"'}
    )

上传大文件时禁用 FastAPI 默认的 form 解析

默认用 UploadFile 接收文件，底层依赖 form 解析器，会把整个上传体缓存到内存或临时文件——上传 500MB 文件时，可能触发 RequestEntityTooLarge 或耗尽磁盘空间。

真正可控的方式是绕过 form，直接读原始 request body 流，自己分块处理。

• 去掉所有 UploadFile 参数，改用 Request 对象
• 用 request.stream() 获取异步迭代器（注意：这是 Starlette 的 stream()，不是 FastAPI 封装过的）
• 别用 await request.body()，它会一次性加载全部内容
• 写入目标文件时用 asyncio.to_thread 包裹 open(..., "wb").write，避免阻塞事件循环

client_max_body_size 和 upload_max_size 不是 FastAPI 配置

很多人在 app = FastAPI(...) 里找上传大小限制参数，找不到是对的——FastAPI 本身不设这个。限制来自部署层：Uvicorn、Nginx 或 Cloudflare。

常见错误是只调大 Uvicorn 的 --limit-concurrency，却忘了它不控制单请求体大小。

• Uvicorn 要加 --limit-max-requests 0 --timeout-keep-alive 5，但真正管 body 大小的是 --limit-request-body（单位字节），例如 --limit-request-body 2147483648 放开到 2GB
• Nginx 必须配 client_max_body_size 2G;，且该指令需放在 http、server 或 location 块中，漏掉任一层都无效
• 若前端走 HTTPS 且经 Cloudflare，还要在 Cloudflare Dashboard 关闭 Web Application Firewall 的“限制上传大小”规则（默认 100MB）

断点续传上传需要自己解析 Range 和 Content-Range

浏览器分片上传（如 axios 的 onUploadProgress）或网络中断重试，依赖 HTTP Range 协议。FastAPI 默认不支持，得手动处理请求头和状态码。

这不是加个装饰器就能搞定的事，涉及文件偏移定位、并发写入冲突、ETag 校验等细节。

• 检查请求头是否有 Range，格式类似 bytes=0-1023；没有则按普通上传走
• 响应必须返回 206 Partial Content，并带 Content-Range 头，例如 Content-Range: bytes 0-1023/2048
• 写文件前先 os.lseek(fd, offset, os.SEEK_SET) 定位，避免覆盖已传部分（注意：Windows 上 lseek 对普通文件句柄有效，但某些异步文件系统需换用 truncate + seek 组合）
• 别忽略 If-Match 头——客户端可能带 ETag 要求校验，不校验会导致重复上传覆盖

FastAPI 的流式能力是够用的，但所有“自动”逻辑（form 解析、文件缓存、MIME 推断）在大文件场景下都是潜在故障点。真正的控制权不在路由函数里，而在你是否愿意放弃封装、直面 socket 层的 chunk、offset 和 header。

终于介绍完啦！小伙伴们，这篇关于《FastAPI大文件流式传输教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！