Hyperf单机部署中Nginx缓存优化的核心是在保障数据实时性前提下分层拦截可缓存流量，降低PHP-FPM/Swoole压力；需覆盖Hyperf默认禁用缓存的响应头，针对静态资源、只读公共接口、签名CDN接口分类缓存，并精简cache_key、启用cache_lock与stale机制。
针对 Hyperf 单机部署场景，Nginx 缓存规则优化的核心目标是：**在保障接口数据实时性与一致性的前提下，分层拦截可缓存流量，显著降低 PHP-FPM（或 Swoole）进程压力，提升整体 QPS 与响应速度**。Hyperf 默认返回的 HTTP 头（如 Cache-Control: no-cache, private）会默认禁用 Nginx 代理缓存，必须主动覆盖或绕过才能生效。
明确哪些内容适合缓存
Hyperf 是典型的动态 API 服务，绝大多数接口不应全局缓存，但以下几类可安全启用：
-
公开静态资源：如
/static/、/public/下的 JS/CSS/图片/字体，可设强缓存（expires 1y+Cache-Control public） -
只读公共接口：如商品列表、文章详情、配置中心等无用户态、无 Cookie 依赖的 GET 接口，可按状态码缓存（如
200缓存 5–30 分钟） -
带签名的 CDN 友好接口：如图片缩略图服务（
/thumb?w=200&h=150&src=xxx），URL 确定性高、幂等，适合 proxy_cache
关闭默认干扰头，启用 proxy_cache
Hyperf 默认返回 Cache-Control: no-cache, private 和 Vary: Cookie，这两项会直接导致 Nginx 跳过缓存。需在 location 中显式覆盖：
- 用
proxy_ignore_headers Cache-Control Expires Set-Cookie Vary;忽略后端返回的干扰头 - 用
proxy_cache_valid 200 302 5m;主动定义有效缓存策略（不依赖后端头） - 若接口不含敏感用户信息，加
proxy_hide_header Set-Cookie;和proxy_hide_header Vary;避免响应头污染缓存键
精准控制缓存键与失效逻辑
避免因 Cookie、User-Agent 或随机 query 参数导致缓存碎片化：
- 用
proxy_cache_key "$scheme$request_method$host$request_uri";剔除无关变量（默认含$cookie_*，需显式精简） - 对含分页/排序参数的接口，可保留关键参数：
proxy_cache_key "$scheme$request_method$host$uri?$arg_page$arg_sort"; - 配合
proxy_cache_lock on;防止缓存击穿；用proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;提升降级可用性
单机部署下的轻量缓存配置示例
适用于 2–4 核 CPU、8GB 内存的 Hyperf 单机环境（无需 SSD，普通 SATA 盘即可）：
# 全局缓存区定义（nginx.conf http 块）
proxy_cache_path /var/cache/nginx/hyperf levels=1:2 keys_zone=hyperf_cache:50m max_size=500m inactive=30m use_temp_path=off;
<h1>server 块内</h1><p>location ~ ^/(api|v1)/products/ {
proxy_pass <a href="https://www.php.cn/link/85237feeff817d9ae295ca736165879d">https://www.php.cn/link/85237feeff817d9ae295ca736165879d</a>;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;</p><pre class="brush:php;toolbar:false;"># 关键：忽略 Hyperf 默认头，启用自定义缓存
proxy_ignore_headers Cache-Control Expires Set-Cookie Vary;
proxy_hide_header Set-Cookie;
proxy_hide_header Vary;
proxy_cache hyperf_cache;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;
proxy_cache_use_stale error timeout updating http_500;
proxy_cache_lock on;
# 精简缓存 key（不带参数时自动剔除）
proxy_cache_key "$scheme$request_method$host$uri";}
location ~* .(js|css|png|jpg|jpeg|gif|ico|svg|woff2|ttf)$ { root /data/hyperf/public; expires 1y; add_header Cache-Control "public, immutable"; }
