在构建 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 的优势与特点：
- 内存效率高： FileResponse 内部实现了文件的分块读取和传输机制，避免了将整个文件加载到内存，从而有效防止内存溢出。
- 性能优异： 由于其流式处理特性，FileResponse 能够更快地开始传输数据，并减少服务器的资源占用。
- 简单易用： 只需提供文件路径，FileResponse 会自动处理文件打开、读取、关闭以及设置必要的 HTTP 头（如 Content-Length）。
- 支持范围请求： 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 应用将能够更稳定、高效地处理大文件下载任务，提供更优质的用户体验。
