当前位置：首页 > 文章列表 > 文章 > python教程 > FastAPI流式传输大文件处理方法

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

2026-04-02 12:47:13 0浏览收藏

本文深入解析了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的精细掌控。

Python如何实现文件流式传输_FastAPI处理大文件下载与上传

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 要求校验，不校验会导致重复上传覆盖