FastAPI流式传输大文件处理方法

本文深入解析了FastAPI在处理超大文件（如2GB视频或压缩包）时的流式传输与上传实战方案：下载端摒弃易致内存溢出的FileResponse，改用StreamingResponse配合自定义分块生成器（如8192字节/次读取），精准设置media_type和Content-Disposition响应头以确保浏览器正确识别并下载；上传端则彻底绕过UploadFile的form解析陷阱，直接通过Request.stream()获取原始字节流，结合异步写入与线程池避免阻塞；同时强调Uvicorn、Nginx和Cloudflare三层部署配置的关键参数（如--limit-request-body、client_max_body_size、WAF上传限制），并点明断点续传需手动解析Range头、返回206状态及安全定位文件偏移——揭示了一个核心真相：大文件场景下，真正的稳定与可控，来自于主动放弃框架“自动化”封装，直面底层HTTP流、chunk与header的精细掌控。

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流式传输大文件处理方法》的详细内容，更多关于的资料请关注golang学习网公众号！