Flask大文件断点续传实现教程

本文深入解析了在 Flask 中实现大文件断点续传的核心技术要点，重点突破了默认 send_file 不支持 Range 请求的限制：通过手动解析并严格校验 Range 请求头（如处理 bytes=100-、越界、非法格式等边界情况），结合二进制文件流式读取与生成器分块 yield（避免内存溢出和句柄泄漏），精准构造 HTTP 206 Partial Content 响应，正确设置 Content-Range、Content-Length 等关键响应头；同时提醒常见陷阱——如空 Range 漏判导致返回全量 200、Content-Range 格式错误、Nginx 缓冲干扰、前端 blob 响应类型缺失等，并给出 curl 快速验证和生产级健壮性建议，真正帮你稳住 GB 级文件上传下载的生命线。

如何用 Flask 返回支持 Range 请求的大文件响应

Flask 默认的 send_file 不处理 Range 头，直接返回整个文件，无法断点续传。必须手动解析 Range 请求头、计算字节偏移、构造 206 Partial Content 响应。

关键不是“怎么发文件”，而是“怎么按需发一部分，并告诉客户端还剩多少”。核心逻辑是：读取请求中的 Range，校验合法性，定位文件偏移，用生成器分块 yield 数据，同时设置 Content-Range、Content-Length 和状态码。

• 必须用 Response 构造响应，不能用 send_file 或 jsonify
• 响应对象需显式设置 status=206、content_type 和 headers
• 文件必须以二进制模式打开（'rb'），且不能提前读入内存
• 推荐使用 os.stat(filepath).st_size 获取总大小，避免 seek(0, 2) 改变文件指针

怎么安全解析和校验 Range 头

客户端可能发送非法、越界或格式错误的 Range，比如 bytes=100-、bytes=-50、bytes=1000-500，甚至多个范围（Flask 场景下通常只支持单范围）。

不要直接用正则硬拆，优先用标准方式提取起始/结束值，并做三重校验：语法是否合法、起始是否非负、结束是否不超文件总长。

• 用 request.headers.get('Range') 获取原始头，为空则走完整下载（可选）
• 匹配 r'bytes=(\d+)-(\d+)?'，注意第二组可为空（如 bytes=100- 表示“从 100 到末尾”）
• 若结束未指定，设为 file_size - 1；若指定但 > file_size - 1，截断为 file_size - 1
• 起始 > 结束 或 起始 >= file_size → 返回 416 Range Not Satisfiable

为什么必须用生成器 + 流式读取

大文件（GB 级）如果一次性 read() 进内存，会触发 OOM；用生成器按 chunk（如 8192 字节）yield，既控制内存占用，又保持响应流式特性，让 Nginx / 客户端能持续接收。

生成器函数本身不执行，只有在 Response 迭代它时才逐块读取。注意：文件句柄要在生成器内打开并 yield 后关闭，或用上下文管理确保释放。

• chunk 大小建议 4KB–64KB，太小增加系统调用开销，太大失去流控意义
• 不要在生成器外 open() 后传 file object 进去——容易被多次迭代或未关闭
• yield 前先 file.seek(start)，再循环 file.read(chunk_size) 直到达到 end - start + 1 字节
• 响应体长度必须等于实际 yield 的字节数，否则客户端解析 Content-Range 会失败

常见 416 或 200 错误怎么快速定位

断点续传失败常表现为：浏览器提示“网络错误”，curl 显示 HTTP/2 416 却没内容，或本该 206 却返回了 200 + 全文件（说明 Range 逻辑被跳过）。

优先检查三处：是否漏判空 Range（导致走默认全量路径）、Content-Range 格式是否拼错（必须是 bytes 100-199/1000，空格和斜杠不能少）、文件大小是否为 0 或 stat 失败返回负值。

• 用 curl -v -H "Range: bytes=100-199" http://localhost:5000/file 手动测试，看响应头和状态码
• 在生成器开头加 print(f"range: {start}-{end}, total: {file_size}") 快速验证参数
• 若 Nginx 在前，确认已配置 proxy_buffering off 和 underscores_in_headers on（部分旧版需要）
• 前端用 XMLHttpRequest 时，需设 responseType = 'blob'，否则 binary 数据会被转成字符串损坏

Flask 断点续传真正的复杂点不在代码行数，而在于 Range 解析的边界 case 和流式响应中文件生命周期的精确控制——这两个地方一松懈，就会出现偶发性截断或句柄泄漏。

本篇关于《Flask大文件断点续传实现教程》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！