macOS 下标准 Nginx 不支持 proxy_cache_range 指令，因其原生不提供范围缓存功能；Range 请求默认透传不缓存，仅完整响应可被缓存，需通过 proxy_cache_valid 等配置缓存全量资源，并结合 CDN 或静态服务等替代方案实现高效分片访问。
macOS 下 Nginx 的 proxy_cache_range 并不是一个原生支持的指令，Nginx 官方版本（包括 macOS 上通过 Homebrew 或源码编译安装的标准版）**默认不提供该指令**。你可能看到的是某些第三方模块（如 nginx-range-cache-module）或混淆了其他功能（如 proxy_cache_valid、proxy_cache_bypass 或内置的字节范围（Range）请求处理逻辑）。
为什么 Nginx 默认不支持 proxy_cache_range？
Nginx 自身对 Range 请求（例如视频拖拽、大文件分片下载）的缓存行为是有限且有明确设计约束的：
- Nginx 仅在启用
proxy_buffering on且后端响应包含完整Content-Length时，才可能缓存整个响应体； - 对于带
Range: bytes=xxx-yyy的请求，Nginx 默认不缓存该 Range 响应本身，而是直接透传给上游，并将响应原样返回给客户端； - 即使整个资源已被缓存（如首次请求了完整文件），Nginx 也不会基于已有缓存“合成”Range响应——它不具备类似 Squid 的 range-aware cache 功能。
如何实现类似“按范围缓存代理”的效果？
虽然不能直接用 proxy_cache_range，但可通过组合配置逼近目标（例如：缓存完整资源 + 支持 Range 请求 + 减少重复回源）：
-
确保完整资源被缓存：让首次全量请求（无 Range 头）命中缓存。需配置
proxy_cache_valid 200 302 1h;等规则，并确认后端返回可缓存的响应（Cache-Control、Expires合理，无no-store）； -
开启 Range 透传与缓冲协同：设置
proxy_buffering on;+proxy_max_temp_file_size 0;（避免临时文件干扰 Range）； -
利用 $sent_http_content_range 判断是否为 Range 响应，配合
proxy_cache_bypass或proxy_no_cache实现精细控制（例如：只对非 Range 请求启用缓存）； - （进阶）使用第三方模块：如 nginx-range-cache-module，它扩展了缓存逻辑，允许对 Range 响应做分片缓存。需自行编译 Nginx 加载该模块，Homebrew 默认不包含。
验证 Range 请求是否走缓存的实用方法
在配置好缓存后，通过日志和响应头快速判断：
- 在
log_format中加入$upstream_cache_status，查看日志中是否出现HIT（注意：Range 请求通常显示MISS或BYPASS，这是正常行为）； - 用
curl -H "Range: bytes=0-999" -I http://your-proxy/file.zip检查响应头：
若返回206 Partial Content且X-Cache: MISS，说明 Range 未缓存（符合预期）；
若首次全量请求curl -I http://your-proxy/file.zip返回200 OK且X-Cache: HIT，说明完整资源已缓存成功； - 观察
upstream_response_time：后续 Range 请求若明显快于首次全量请求，可能得益于内核缓存或上游优化，而非 Nginx 缓存。
替代方案建议（更简单可靠）
如果核心目标是提升大文件/媒体服务性能，优先考虑以下更成熟路径：
- 前端 CDN + Range 支持：Cloudflare、AWS CloudFront、阿里云 CDN 均原生支持 Range 缓存与边缘合成，配置简单，效果显著；
-
Nginx 静态文件服务 + range 支持：若源文件可落地到本地磁盘，直接用
location匹配静态路径，Nginx 对本地文件天然支持高效 Range 缓存（通过sendfile和内核零拷贝）； - 反向代理层前置对象存储：将 S3 / MinIO 作为上游，Nginx 代理其预签名 URL，由对象存储自身处理 Range 与缓存（如 S3 配合 CloudFront）。
总之，macOS 下标准 Nginx 不支持 proxy_cache_range，也不建议强行编译第三方模块用于生产。理解其 Range 处理机制，结合缓存完整资源 + 合理架构选型，才是稳定高效的解法。
