FileResponse是最稳妥的文件下载方式，需设media_type为”application/octet-stream”并用headers设置Content-Disposition；动态文件用StreamingResponse，注意编码、分块yield及中文名用filename*兼容RFC 5987。
FastAPI 中用 FileResponse 实现文件下载并设置 Content-Disposition
直接用 FileResponse 是最稳妥的方式，它自动处理文件流、MIME 类型和缓存头，且支持通过 headers 参数注入 Content-Disposition。关键点是：必须显式指定 media_type 为 "application/octet-stream"（除非你希望浏览器尝试内联打开），否则某些文件类型（如 .txt、.json）可能被浏览器直接渲染而非下载。
示例：
from fastapi import FastAPI
from fastapi.responses import FileResponse
import pathlib
app = FastAPI()
@app.get("/download")
def download_file():
file_path = pathlib.Path("report.pdf")
return FileResponse(
path=file_path,
media_type="application/octet-stream",
headers={"Content-Disposition": 'attachment; filename="report.pdf"'}
)
-
filename值建议用英文或 URL 编码过的字符串；中文名在部分客户端（如旧版 Safari）可能乱码或截断，可考虑用filename*=UTF-8''report%E6%8A%A5%E5%91%8A.pdf格式 - 如果文件路径来自用户输入，务必做路径校验（如用
pathlib.Path.resolve()防止目录遍历） -
FileResponse不支持动态生成的字节流——此时得换StreamingResponse
用 StreamingResponse 下载动态生成的文件（如 ZIP 或 CSV 流）
当文件内容不落地、需边生成边传输时，FileResponse 不适用，必须用 StreamingResponse，手动构造响应体和头。此时 Content-Disposition 仍靠 headers 传入，但 MIME 类型和响应体流需自己把控。
示例（生成 CSV 流）：
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import io
import csv
app = FastAPI()
@app.get("/export-csv")
def export_csv():
def iter_csv():
output = io.StringIO()
writer = csv.writer(output)
writer.writerow(["id", "name"])
writer.writerow([1, "Alice"])
yield output.getvalue().encode("utf-8")
return StreamingResponse(
iter_csv(),
media_type="text/csv",
headers={"Content-Disposition": 'attachment; filename="data.csv"'}
)
- 注意编码：CSV 流推荐用
utf-8，并在media_type后加; charset=utf-8更明确 - 流函数必须是可迭代的（
Generator或返回迭代器），不能直接 return 字符串 - 大文件流场景下，避免在内存中拼接全部内容，应分块
yield
Content-Disposition 的两种取值：inline vs attachment
这个响应头决定浏览器行为：inline 表示允许内联显示（如 PDF 在浏览器中打开），attachment 强制触发下载对话框。实际使用中，绝大多数“下载”需求都该用 attachment，否则用户可能看不到文件保存动作。
- 错误写法：
Content-Disposition: inline; filename="log.txt"→ 用户看到的是页面里一堆文本，不是下载 - 正确写法：
Content-Disposition: attachment; filename="log.txt" - 如果想兼容内联预览又保留下载能力，现代做法是前端用
或fetch + Blob + URL.createObjectURL控制，后端统一用attachment
常见问题：中文文件名乱码或被截断
HTTP 协议本身不支持 UTF-8 文件名，RFC 5987 规定了 filename* 扩展语法。FastAPI 不自动处理，需手动构造。
安全写法（兼容主流浏览器）：
from urllib.parse import quote
filename = "报告2024.xlsx"
encoded_filename = quote(filename.encode("utf-8"))
headers = {
"Content-Disposition": f'attachment; filename="{filename}"; filename*=UTF-8/'/'{encoded_filename}'
}
- 两个
filename字段同时存在是故意的：老客户端读第一个，新客户端读filename* - 不要只写
filename*，IE 和部分旧版本 Chrome 会忽略它 -
quote(...)用的是urllib.parse.quote，不是quote_plus（空格应编码为%20，不是+）
实际部署时，Nginx 等反向代理可能覆盖或清空 Content-Disposition，记得检查其配置里是否禁用了自定义头。