nginx location 支持断点续传的关键是保持 range 功能不被禁用或干扰:需移除 max_ranges 0、慎用 sendfile 和 gzip、确保文件可读且无拦截逻辑、代理时透传 range 头、mp4 需启用 mp4_module 并含 faststart 头。

要让 Nginx 的 location 块真正支持 HTTP 断点续传,关键不是“开启”某个开关,而是避免误关、确保透传、排除干扰。Nginx 1.1.3+ 默认就具备 Range 处理能力,配置的核心是“不破坏它”。
确认 location 中未禁用 range 功能
以下配置会直接关闭断点续传,必须检查并移除或修正:
-
max_ranges 0; —— 彻底禁用所有 Range 请求,应删掉该行,或设为
max_ranges 10;(允许最多 10 个范围) -
sendfile on; —— 在某些内核或小文件场景下与 Range 冲突,若验证失败可临时改为
sendfile off;测试 -
gzip on; 对大文件启用 gzip 压缩会破坏 Content-Range,建议对 zip/mp4/iso 等二进制文件禁用:
gzip off;或用gzip_disable "msie6";+ 条件判断
静态文件路径需保证可读且无拦截逻辑
Range 请求只有在成功命中真实文件、且未被中间指令截断时,才能返回 206。确保:
- root 或 alias 指向的目录权限正确,文件存在且大小可获取(
stat()成功) - 没有
rewrite、satisfy、auth_basic、limit_req等指令在匹配后跳过原处理流程 - 避免在该 location 中使用
try_files指向非静态处理器(如 PHP),否则 Range 不生效
代理场景下必须显式透传 Range 相关头
如果该 location 是反向代理(例如 proxy_pass 到后端服务或 CDN),Nginx 默认不转发 Range 和 If-Range,需手动补全:
proxy_set_header Range $http_range;proxy_set_header If-Range $http_if_range;-
proxy_pass_request_headers on;(确保其他必要头也不丢失) - 禁用对该请求的缓存:
proxy_cache_bypass $http_range;或直接proxy_cache off;
MP4 视频拖拽播放需额外启用 mp4_module
普通文件支持 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 头,即表示配置成功。










