<p>应使用 send_file 而非 send_from_directory 实现安全下载：需校验路径防穿越、清洗 download_name、手动构造 Content-Disposition（含 filename* 编码）、禁用缓存头、大文件采用流式响应。</p>
用 send_file 而不是 send_from_directory 控制下载行为
直接返回文件内容并强制浏览器下载，关键在响应头和文件流控制。send_file 更灵活，能显式设 as_attachment=True 和自定义 download_name，避免路径遍历风险；send_from_directory 仅适合公开静态资源服务，不支持动态重命名或安全校验。
常见错误是硬拼路径后调用 send_from_directory，结果用户传 ../../etc/passwd 就可能触发目录穿越。正确做法是：先校验文件归属、再读取为字节流、最后交由 send_file 输出。
- 必须用
os.path.abspath和os.path.commonpath校验请求路径是否在白名单目录内 -
download_name参数要清洗，去掉路径分隔符和控制字符，防止响应头注入 - 不要用
io.BytesIO包裹大文件再传给send_file，会吃光内存；优先传文件路径或带seekable=False的流
设置 Content-Disposition 响应头的细节差异
浏览器是否弹出下载框，取决于 Content-Disposition 头里的 filename 和 filename* 字段。Flask 的 send_file 默认只写 filename，对中文名或特殊字符支持差，容易乱码或截断。
真正兼容的做法是手动构造这个头：用 filename*（RFC 5987）传 UTF-8 编码值，同时保留 filename 作为 fallback。Flask 不自动帮你做这层编码，得自己处理。
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
-
filename只能是 ASCII，长度建议 ≤100 字符，否则部分旧版 IE 会丢弃整个头 -
filename*格式为UTF-8''{encoded}，需用urllib.parse.quote编码原始文件名 - 别漏掉
Content-Type: application/octet-stream，否则某些浏览器可能尝试渲染文本文件
绕过 Flask 默认缓存策略避免 304 响应干扰下载
如果用户重复点击下载链接，Flask 可能返回 304 Not Modified，导致前端收不到文件流。这不是 bug，而是它默认启用了基于 ETag 和 Last-Modified 的条件响应。
下载场景下，你希望每次点击都拿到完整响应体，而不是让浏览器复用缓存。最简单有效的办法是禁用相关头字段，并显式设置 Cache-Control。
- 在
send_file调用后，用response.headers.pop('ETag', None)和response.headers.pop('Last-Modified', None)清除 - 加一句
response.headers['Cache-Control'] = 'no-cache, no-store, must-revalidate' - 别依赖
max_age=0，它仍可能触发条件请求；no-store才真正禁止缓存实体
大文件下载时用 Response 流式传输防超时
当文件超过几十 MB，用 send_file 加载进内存再发，容易触发 Gunicorn 或 Nginx 的 timeout，也占满 worker 进程。这时该切换成流式响应。
核心是把文件以块（如 8192 字节）读取，包装成生成器，喂给 Response。注意不能用 with open() 在生成器外提前关闭句柄，也不能依赖 send_file 的自动 close 行为。
- 打开文件时加
buffering=0或用os.open+os.fdopen避免 Python 缓冲干扰流控 - 生成器函数里必须
yieldbytes，不能 yield str；且每次 yield 后最好time.sleep(0)让出协程，防阻塞 - Nginx 前置时，记得关掉
proxy_buffering off，否则它会攒满 128k 才转发，破坏流式效果
最易被忽略的是文件名编码和缓存头清理——它们不出错，但会让下载在某些浏览器上静默失败。尤其是企业内网还跑着 IE11 或旧版 Edge 的环境，filename* 缺失或 Cache-Control 没关，问题就藏得很深。
