fastapi 如何实现文件下载响应且设置 Content-Disposition

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 = "报告2025.xlsx"
encoded_filename = quote(filename.enc
ode("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，记得检查其配置里是否禁用了自定义头。