FastAPI 大文件高效传输：使用 FileResponse 避免内存溢出

在构建 web 服务时，文件下载是一个常见需求。然而，当文件体积较大时，不当的处理方式可能导致服务器内存耗尽，尤其是在高并发场景下。fastapi 提供多种响应类型，理解它们的适用场景对于优化性能至关重要。

大文件下载的常见误区与内存问题

许多开发者在尝试使用 StreamingResponse 返回文件时，可能会遇到内存溢出（Out Of Memory, OOM）的问题。一个常见的错误模式是，在将文件内容传递给 StreamingResponse 之前，使用 file.read() 方法一次性读取整个文件到内存中，如下所示：

import io
from fastapi import FastAPI
from starlette.responses import StreamingResponse

app = FastAPI()

@app.get("/download-large-file-problematic")
async def download_large_file_problematic():
    filename = "path/to/your/large_file.zip" # 假设这是一个非常大的文件
    try:
        # ⚠️ 严重问题：file.read() 会一次性加载整个文件到内存
        with open(filename, "rb") as f:
            file_content = f.read()

        headers = {'Content-Disposition': f'attachment; filename="{filename.split("/")[-1]}"'}
        # io.BytesIO(file_content) 同样需要整个文件内容在内存中
        return StreamingResponse(
            content=io.BytesIO(file_content), 
            media_type="application/octet-stream", 
            headers=headers
        )
    except FileNotFoundError:
        return {"message": "File not found"}

尽管在 open() 函数中使用了 buffering 参数，但 io.BytesIO(file.read()) 这一操作本身就意味着整个文件的内容首先被 file.read() 加载到内存，然后再封装成 BytesIO 对象。对于 GB 级别的大文件，这会迅速耗尽服务器的可用内存，导致服务崩溃。

解决方案：使用 FileResponse 高效传输大文件

FastAPI (实际上是其底层 Starlette) 提供了一个专门用于文件传输的响应类：FileResponse。FileResponse 的设计初衷就是为了高效地处理本地文件传输，它直接接收文件路径作为参数，并负责以流式方式（分块）读取和发送文件内容，而无需将整个文件加载到内存中。这极大地优化了内存使用和传输效率。

以下是使用 FileResponse 解决大文件下载问题的正确方法：

from fastapi import FastAPI
from starlette.responses import FileResponse
import os

app = FastAPI()

# 假设你的项目根目录下有一个名为 'static' 的文件夹，其中包含 large_file.zip
# 为了演示，我们先创建一个虚拟的大文件
# import os
# with open("static/large_file.zip", "wb") as f:
#     f.seek(1024 * 1024 * 100 - 1) # 100 MB
#     f.write(b'\0')

@app.get("/download-large-file-optimized")
async def download_large_file_optimized():
    file_path = "static/large_file.zip" # 替换为你的实际文件路径

    if not os.path.exists(file_path):
        return {"message": "File not found"}, 404

    # FileResponse 直接接收文件路径
    # 它会负责以流式方式读取和发送文件，无需一次性加载到内存
    return FileResponse(
        path=file_path,
        media_type="application/zip", # 根据文件类型设置正确的 media_type
        filename="my_large_file.zip", # 提供给用户下载的文件名
        headers={"Content-Disposition": f"attachment; filename=my_large_file.zip"}
    )

FileResponse 的优势与特点：

存了个图

视频图片解析/字幕/剪辑，视频高清保存/图片源图提取

17

查看详情

1. 内存效率高： FileResponse 内部实现了文件的分块读取和传输机制，避免了将整个文件加载到内存，从而有效防止内存溢出。
2. 性能优异： 由于其流式处理特性，FileResponse 能够更快地开始传输数据，并减少服务器的资源占用。
3. 简单易用： 只需提供文件路径，FileResponse 会自动处理文件打开、读取、关闭以及设置必要的 HTTP 头（如 Content-Length）。
4. 支持范围请求： FileResponse 默认支持 HTTP 范围请求（Range Requests），这意味着客户端可以恢复中断的下载，或者只请求文件的一部分。

FileResponse 参数详解

• path (str | Path): 必需参数，要返回的文件的本地文件系统路径。
• media_type (str | None): 可选参数，响应的 MIME 类型。如果未指定，FileResponse 会尝试根据文件扩展名自动推断。
• filename (str | None): 可选参数，客户端下载文件时显示的名称。通常与 Content-Disposition 头部的 filename 字段一同使用。
• stat_result (os.stat_result | None): 可选参数，如果已提前获取文件状态信息，可以传入，避免 FileResponse 再次调用 os.stat()。
• headers (dict | None): 可选参数，额外的 HTTP 响应头。常用于设置 Content-Disposition 以强制浏览器下载文件而非在浏览器中打开。
• background (BackgroundTask | None): 可选参数，一个 BackgroundTask 对象，用于在响应发送完成后执行一些清理工作，例如删除临时文件。

StreamingResponse 的适用场景

尽管 FileResponse 是处理本地大文件的首选，但 StreamingResponse 并非毫无用处。它适用于以下场景：

• 动态生成的内容： 当文件内容不是存储在磁盘上，而是实时生成（例如，从数据库中读取 BLOB 数据，或者进行实时数据流处理）时。
• 来自外部源的流： 当你从另一个 API 或网络服务获取数据流，并希望直接将其转发给客户端时。
• 需要自定义流逻辑： 当你需要对数据流进行复杂的处理或转换，而 FileResponse 无法满足时。

在这种情况下，StreamingResponse 接收一个可迭代对象（通常是生成器），每次迭代返回一个数据块，从而实现流式传输。

总结与建议

在 FastAPI 中处理文件下载时，选择正确的响应类型至关重要。

• 对于存储在本地文件系统中的大文件，始终优先使用 FileResponse。 它能够高效地处理文件传输，避免内存溢出，并提供良好的性能。
• 对于动态生成或来自非文件系统的流式内容，使用 StreamingResponse。 确保你的内容源是可迭代的，并且每次只产生一小部分数据，以避免一次性加载所有内容。

通过遵循这些最佳实践，你的 FastAPI 应用将能够更稳定、高效地处理大文件下载任务，提供更优质的用户体验。

以上就是FastAPI 大文件高效传输：使用 FileResponse 避免内存溢出的详细内容，更多请关注php中文网其它相关文章！