根本原因是生成器未真正流式yield，而是在内存中攒完整文件再返回；需确保每次yield bytes且分块读取（8kb–64kb），避免read()或getvalue()，并正确设置content-length和content-disposition。
用 StreamingResponse 时为什么文件下载还是卡在 0%？
根本原因不是没流，而是你返回的生成器没真正“边读边 yield”，而是在内存里攒完整个文件再吐——这和直接返回 FileResponse 没区别。
常见错误现象：curl -v 看到 Content-Length 正确但 Transfer-Encoding: chunked 没触发，浏览器进度条不动，直到最后才一次性写入；或 FastAPI 报 Response body is not iterable。
- 确保生成器函数每次
yield的是bytes（不是str），且单次大小建议 8KB–64KB（太小增加 syscall 开销，太大失去流式意义） - 别用
open(...).read()或io.BytesIO().getvalue()，改用open(..., 'rb').read(chunk_size) - FastAPI 会自动设
Content-Transfer-Encoding: chunked，但前提是响应体确实是可迭代的bytes流，不是一次性对象
StreamingResponse + background_tasks 清理临时文件的坑
大文件下载常需先生成临时路径（比如导出报表），但用户关掉页面、中断请求后，临时文件没人删——磁盘迟早爆。
不能只靠 finally 或同步 os.remove：异步上下文里文件句柄可能还在用，PermissionError 或 FileNotFoundError 很常见。
立即学习“Python免费学习笔记（深入）”；
- 用
BackgroundTasks.add_task()而不是裸调函数，确保任务在响应结束后执行 - 删除前加
try/except OSError，因为文件可能已被其他请求清理过 - 更稳的做法：用带 TTL 的临时目录（如
tempfile.TemporaryDirectory(dir='/tmp/downloads')），配合定时 job 扫描过期文件，而不是依赖单次请求生命周期
浏览器不显示进度条？检查 Content-Disposition 和 Content-Length
流式响应默认没有 Content-Length，浏览器就无法计算百分比。但强制设它又容易错——比如文件边生成边变长，或者压根不知道最终大小。
真实场景中，90% 的“提速”感知来自进度可见，而不是纯吞吐提升。
- 如果文件大小已知（如查 DB 后确定导出行数），务必显式传
headers={'Content-Length': str(size)}给StreamingResponse -
Content-Disposition必须含filename=，否则 Safari 拒绝触发下载，Chrome 可能存成无后缀乱码名；推荐写法：Content-Disposition: attachment; filename="report_2024.csv" - 不要用
filename*=UTF-8''...编码中文名——兼容性差，老版 Edge 和部分企业内网浏览器直接失败
并发下载多文件时，StreamingResponse 阻塞整个事件循环？
问题不在 StreamingResponse 本身，而在你用的文件读取方式：同步 open() + .read() 会阻塞 event loop，一个慢连接拖垮所有请求。
尤其当文件在 NFS 或低速存储上时，单次 read() 可能卡几百毫秒，而 FastAPI 默认只有 1 个 worker 线程处理 I/O。
- 用
asyncio.to_thread()包一层同步读操作（Python 3.9+），避免阻塞主线程 - 或改用
aiofiles库（注意它不支持所有文件系统，Windows 上某些挂载点会报Operation not supported） - 更彻底的方案：把大文件读取下沉到独立进程（
multiprocessing.Pool），通过Queue向主协程推送bytes块——适合 >500MB 场景，但运维成本上升
流式下载真正的复杂点从来不在“怎么写 yield”，而在于你怎么应对磁盘延迟、客户端断连、临时资源回收和并发调度——这些地方一松懈，提速就变成添堵。
