如何在flet-fastapi中实现FileResponse/StreamingResponse文件下载？

核心排查与修复步骤 #

1. 确保文件路径绝对且有效 #

• FastAPI的FileResponse依赖准确的文件位置，务必使用绝对路径避免相对路径导致的文件找不到问题。
• 示例代码：

  from pathlib import Path
  # 基于当前脚本位置生成绝对路径
  file_path = Path(__file__).parent / "generated" / "user_info.docx"
  

• 返回前强制校验文件存在性：

  if not file_path.exists() or not file_path.is_file():
      raise HTTPException(status_code=404, detail="目标文件未生成或路径无效")
  

2. 适配Flet-FastAPI的路由逻辑 #

Flet的页面回调不能直接返回FileResponse，需单独定义FastAPI原生路由处理下载请求：

from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse
import flet as ft
from flet_fastapi import FletFastAPI
from pathlib import Path

app = FastAPI()
flet_app = FletFastAPI(app)

# 原生FastAPI路由处理文件下载
@app.get("/download-doc")
async def download_document():
    file_path = Path(__file__).parent / "generated" / "user_info.docx"
    return FileResponse(
        path=file_path,
        filename="用户信息文档.docx",
        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )

# Flet页面交互逻辑
@flet_app.route("/")
async def main_page(request):
    return ft.View(
        "/",
        controls=[
            ft.ElevatedButton("生成并下载文档", on_click=lambda e: e.page.launch_url("/download-doc"))
        ]
    )

3. 正确配置响应参数 #

• 必须指定.docx对应的media_type：application/vnd.openxmlformats-officedocument.wordprocessingml.document，否则浏览器无法识别文件类型。
• 显式设置filename参数，确保下载时文件名符合预期。

4. 临时文件的清理（可选） #

若生成的是临时文件，可通过BackgroundTasks在响应返回后自动清理：

from fastapi import BackgroundTasks

def remove_temp_file(file_path: Path):
    if file_path.exists():
        file_path.unlink()

@app.get("/download-doc")
async def download_document(background_tasks: BackgroundTasks):
    file_path = Path(__file__).parent / "generated" / "user_info.docx"
    background_tasks.add_task(remove_temp_file, file_path)
    return FileResponse(
        path=file_path,
        filename="用户信息文档.docx",
        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
    )

异常定位技巧 #

如果仍抛出FastAPIError，可以：

• 打印file_path的绝对路径，手动确认文件是否存在。
• 捕获异常并输出详细信息：

  try:
      return FileResponse(...)
  except Exception as e:
      print(f"返回文件时出错: {str(e)}")
      raise HTTPException(status_code=500, detail=str(e))
  

内容的提问来源于stack exchange，提问作者ponkipop