Nginx location 块支持 HTTP 断点续传的关键是避免禁用 Range、确保透传、排除干扰;需移除 max_ranges 0,慎用 sendfile/gzip,禁用拦截指令,代理时透传 Range 头,MP4 需启用 mp4 模块并含 moov 头。

让 Nginx 的 location 块真正支持 HTTP 断点续传(Range 请求),核心不是“开启”什么功能,而是避免误关、确保透传、排除干扰。Nginx 1.1.3+ 默认具备 Range 处理能力,配置重点在于“不破坏它”。
确认未禁用 Range 功能
以下配置会直接关闭断点续传,必须检查并移除或修正:
-
max_ranges 0; —— 彻底禁用所有 Range 请求,应删掉该行,或设为
max_ranges 10;(允许最多 10 个范围) -
sendfile on; —— 在某些内核或小文件场景下与 Range 冲突,若验证失败可临时改为
sendfile off; -
gzip on; —— 对 zip/mp4/iso 等二进制文件启用 gzip 会破坏
Content-Range,建议禁用:gzip off;,或用gzip_disable "msie6";加条件判断
确保静态文件路径无拦截逻辑
Range 请求只有在成功命中真实文件、且未被中间指令截断时,才能返回 206 Partial Content:
-
root 或 alias 指向的目录需权限正确,文件存在且大小可获取(
stat()成功) - 避免在该
location中使用rewrite、satisfy、auth_basic、limit_req等指令,防止跳过原处理流程 - 不要用
try_files指向 PHP 等非静态处理器,否则 Range 不生效
代理场景下必须透传 Range 相关头
若该 location 使用 proxy_pass,Nginx 默认不转发 Range 和 If-Range,需手动补全:
-
proxy_set_header Range $http_range;—— 原样透传客户端 Range 值 -
proxy_set_header If-Range $http_if_range;—— 配合 Range 使用,避免重试时降级为 200 响应 - 添加
proxy_cache_bypass $http_range;或直接proxy_cache off;,禁用对该请求的缓存
MP4 视频拖拽播放需额外支持
普通文件支持 Range,但 MP4 快速拖动依赖两个前提:
- Nginx 编译时包含
--with-http_mp4_module(运行nginx -V 2>&1 | grep mp4验证) - MP4 文件本身含
moov头(faststart),可用 FFmpeg 重写:ffmpeg -i in.mp4 -c copy -movflags +faststart out.mp4 - 在
location中添加mp4;指令,并可选调优缓冲:mp4_buffer_size 1m;、mp4_max_buffer_size 5m;
验证是否生效:用 curl 发起测试请求:curl -I -H "Range: bytes=0-1023" https://your.site/file.zip
返回 206 Partial Content 且含 Accept-Ranges: bytes 和 Content-Range 字段,即表示配置成功。










