proxy_cache_max_range_offset用于限制nginx代理缓存中range请求的起始偏移量，防止大文件尾部随机range导致缓存碎片化和资源浪费；仅当range起始字节≤该值时才缓存，推荐设为1m～10m并配合含$http_range的cache_key使用。
proxy_cache_max_range_offset 是 Nginx 代理缓存中一个控制「范围请求（Range request）」缓存行为的参数，主要用于限制单个缓存项支持的最大字节偏移量，防止因超大文件的随机 Range 请求导致缓存碎片化或内存/磁盘资源被异常占用。
它解决什么问题？
当客户端发起 HTTP Range 请求（例如下载大文件时断点续传、视频拖拽播放），Nginx 默认会尝试缓存该 Range 对应的片段。但如果不对偏移量设限，可能产生以下风险：
- 一个 10GB 视频文件，客户端请求
Range: bytes=9999999999-，Nginx 会为这个极靠后的片段单独建缓存条目，但实际内容极少甚至为空，造成元数据膨胀和磁盘浪费 - 多个不同 offset 的小 Range 请求，累积生成大量零散缓存块，降低缓存命中率与清理效率
- 配合
proxy_cache_key中未包含$http_range时，还可能引发缓存污染（不同 Range 被错误复用同一缓存体）
它的作用机制
该参数不决定是否缓存 Range 请求，而是设定「允许缓存的 Range 片段最大起始偏移量」。Nginx 在收到 Range 请求后会做如下判断：
- 若请求的
bytes=N-中N > proxy_cache_max_range_offset值，则该请求不进入缓存流程，直接透传给上游服务器 - 若
N ≤设定值，且满足其它缓存条件（如状态码、proxy_cache_valid等），则按正常逻辑缓存该 Range 片段 - 注意：它只限制起始 offset，不限制 Range 长度；也不影响完整响应（非 Range）的缓存
典型配置建议
默认值为 无限制（即不限制），生产环境建议显式设置。常见合理取值范围在 1m～10m 之间，例如：
proxy_cache_max_range_offset 2m;
含义：仅缓存起始位置在前 2MB 内的 Range 请求（如 bytes=0-1023、bytes=1048576-2097151），而 bytes=2097152- 及之后的请求一律不缓存。
搭配使用时需注意：
- 若启用 Range 缓存，
proxy_cache_key应包含$http_range，否则不同 Range 可能共用同一缓存键，导致返回错误内容 - 配合
proxy_cache_use_stale updating可提升高并发 Range 场景下的响应稳定性 - 该指令可出现在
http、server或location块中，按需覆盖
验证是否生效
可通过日志观察 $upstream_cache_status 变量：
- 命中缓存 Range：显示
HIT或UPDATING - 跳过缓存：显示
BYPASS或MISS（取决于是否满足其它 bypass 条件） - 添加响应头便于调试：
add_header X-Cache-Status $upstream_cache_status;
