StreamingHttpResponse 更适合大文件下载，因其边读边发、内存占用恒定；需配 Nginx proxy_buffering off，设正确 Content-Type 与 Content-Disposition，用迭代器分块读取并校验路径与权限。
StreamingHttpResponse 为什么比 HttpResponse 更适合文件下载
大文件直接用 HttpResponse 会把整个文件读进内存再发出去，容易 OOM；StreamingHttpResponse 是边读边发，内存占用恒定，适合 GB 级日志、导出报表等场景。
它不缓存响应体，而是接收一个可迭代对象（比如生成器），每次 yield 一块数据，由 WSGI/ASGI 服务器逐块写入 socket。Nginx 默认会缓冲响应，所以还得配 proxy_buffering off，否则前端仍要等全部传输完才开始下载。
- 必须设置
Content-Type和Content-Disposition，否则浏览器可能当成文本打开 - 不能用
render或模板，它绕过 Django 模板渲染层 - 视图函数里不能有中间件修改响应体（比如
CommonMiddleware的 ETag 自动计算会失败）
怎么写一个安全的文件流式下载视图
核心是构造一个能按块读取的迭代器，同时处理路径校验、权限、文件名编码。别直接拼接用户传入的 file_path，也别用 open() 读整个文件。
def download_file(request):
file_id = request.GET.get('id')
obj = get_object_or_404(Document, id=file_id, owner=request.user)
def file_iterator(file_path, chunk_size=8192):
with open(file_path, 'rb') as f:
while True:
chunk = f.read(chunk_size)
if not chunk:
break
yield chunk
response = StreamingHttpResponse(
file_iterator(obj.file.path),
content_type='application/octet-stream'
)
response['Content-Disposition'] = f'attachment; filename="{obj.filename}"'
return response
-
filename要做安全过滤：去掉路径遍历字符（..、/）、控制非法 Unicode（比如 null 字节） - 如果文件在 S3 或其他远程存储，别用
open()，改用boto3.client.get_object(Bucket=..., Key=...)的StreamingBody直接 yielditer_lines()或分块读 - Django 4.2+ 支持
StreamingHttpResponse的headers参数，但Content-Length通常不设——流式响应没法预知总大小
中文文件名乱码或下载失败的常见原因
浏览器对 Content-Disposition 中的中文处理不一致：Chrome 支持 filename*=UTF-8''... 编码格式，IE/Edge 只认 filename 的 GBK 编码（已淘汰），Firefox 折中。Django 默认不自动编码，得手动处理。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
- 推荐方案：用
urllib.parse.quote编码文件名，再拼进filename*=UTF-8''...格式 - 示例：
f'attachment; filename="{obj.filename}"; filename*=UTF-8\'\'{quote(obj.filename)}' - 注意
quote默认不编码斜杠，要加safe=''参数，否则/会被转成%2F - 如果用了 Nginx，确认没开启
underscores_in_headers on，否则带下划线的 header（如Content_Disposition）会被丢弃
调试时看到 “Response headers already written” 错误
这是 StreamingHttpResponse 最典型的报错，意味着你在 yield 数据前，已经写了响应头（比如调了 response.write()、或者中间件提前设置了某些 header）。
- 检查有没有自定义中间件在
process_response里修改了StreamingHttpResponse实例 - 确保视图返回前没调用
response.set_cookie()或response['X-Custom'] = ...——这些操作必须在构造响应对象时完成 - 别在生成器函数里抛异常（比如
open()失败），异常会中断流，但 header 已发出，后续 error page 就写不进去了；应该在生成器外先校验文件是否存在 - Gunicorn 默认超时 30 秒，大文件下载慢会被 kill，记得调大
--timeout和--keep-alive
流式响应本质是把控制权交给了底层服务器和网络栈，Django 层能干预的点很少。真正卡住的地方往往不在 Python 代码里，而在 Nginx 配置、反向代理超时、客户端断连重试逻辑上。
