Nginx 中 proxy_cache_max_range_offset 设置流式响应缓存-Nginx-PHP中文网

proxy_cache_max_range_offset 限制range响应缓存的字节偏移上限（默认1mb），即起始位置加该值须不小于content-range结束位置才允许缓存；它不控制流式响应缓存，关键在proxy_cache_key含$http_range及显式配置proxy_cache_valid 206。

nginx 中 proxy_cache_max_range_offset 设置流式响应缓存

proxy_cache_max_range_offset 并不用于控制流式响应（如视频、音频分片）的缓存行为，它和 range 请求的缓存范围限制有关，但与“流式响应缓存”没有直接关系。Nginx 本身对流式内容（如 HTTP Range 请求）的缓存支持有限，且 proxy_cache_max_range_offset 的作用被广泛误解。

它实际做什么？

该指令限制 Nginx 在处理 Range 请求时，允许缓存并返回的最大字节偏移量（从文件开头起算）。当上游响应带 Content-Range 头（例如 bytes 1000-1999/10000），且结束位置超过 start + proxy_cache_max_range_offset 时，Nginx 将拒绝缓存该响应，即使整个响应体已接收完成。

默认值为 1048576（1MB），意味着只缓存 Range 响应中「起始偏移 + 最多 1MB」以内的片段
若请求 Range: bytes=2000000-2999999，而 proxy_cache_max_range_offset 1048576，则 2000000 + 1048576 = 3048576 > 2999999 → 允许缓存
若请求 Range: bytes=5000000-5999999，则 5000000 + 1048576 = 6048576 > 5999999 → 仍允许
但若请求 Range: bytes=5000000-6500000（跨度 1.5MB），超出了 offset 限制 → 不缓存该响应

它不能解决流式缓存的核心问题

真正影响流式内容缓存效果的是以下几点，而非此参数：

Range 请求是否被缓存：需显式开启 proxy_cache_key 包含 $http_range 和 $http_if_range
上游是否支持可缓存的 Range 响应：响应必须含 Accept-Ranges: bytes、ETag 或 Last-Modified，且状态码为 206
缓存策略是否允许 206 响应缓存：需用 proxy_cache_valid 206 1h; 显式配置
缓存 key 是否区分 range 范围：否则不同 range 可能命中同一缓存实体，导致内容错乱

如何正确配置 Range 缓存

典型安全有效的流式缓存配置示例：

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

proxy_cache_valid 200 206 1h;
proxy_cache_key "$scheme$request_method$host$request_uri$http_range";
proxy_ignore_headers Cache-Control Expires Set-Cookie;
proxy_cache_use_stale http_502 http_503 http_504;

注意：$http_range 必须加入 proxy_cache_key，否则所有 range 请求共用一个缓存 entry，极易出错。