proxy_cache_convert_head指令使nginx将head请求自动转为get请求以获取并缓存响应头及内容，提升缓存复用率；需配合proxy_cache等配置启用，要求后端支持get响应。
在 Nginx 中，proxy_cache_convert_head 指令的作用正是解决这个问题：它让 Nginx 在收到客户端发来的 HEAD 请求时，**自动将其转换为 GET 请求去后端获取响应头和缓存内容**，从而实现对缓存的复用。默认情况下，HEAD 请求不会触发缓存存储（因为不带响应体），也无法命中已缓存的 GET 响应，导致缓存利用率下降。
为什么需要开启 proxy_cache_convert_head
HEAD 请求只关心响应头（如 Last-Modified、ETag、Content-Length），不携带响应体。Nginx 默认不会为 HEAD 请求生成或查找缓存条目，即使对应 URL 的 GET 请求早已被缓存。这会造成：
- 重复向后端发起 HEAD 请求，增加上游压力
- 无法利用已有缓存做条件请求验证（如
If-None-Match） - 缓存命中率统计失真，实际可缓存资源未被有效复用
正确配置 proxy_cache_convert_head
该指令需在 location 或 server 块中启用，且必须配合缓存相关配置使用：
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
- 确保已启用
proxy_cache并配置了有效的缓存区（如proxy_cache my_cache） - 设置
proxy_cache_valid，尤其要包含对200和304状态的缓存时间 - 添加
proxy_cache_convert_head on;即可生效
示例片段：
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g;<br>upstream backend { server 127.0.0.1:8080; }<br><br>server {<br> location / {<br> proxy_pass http://backend;<br> proxy_cache my_cache;<br> proxy_cache_valid 200 302 10m;<br> proxy_cache_valid 404 1m;<br> proxy_cache_convert_head on;<br> add_header X-Cache-Status $upstream_cache_status;<br> }<br>}
注意事项与常见问题
启用后需注意以下几点：
- 后端必须能正常处理 GET 请求并返回完整响应（含 body），否则转换失败会导致 502
- Nginx 会缓存 GET 响应的完整内容（包括 body），但对 HEAD 请求仅返回响应头 —— 这是预期行为
- 若后端对 HEAD 和 GET 返回不同响应头（如动态计算
Content-Length），可能引发不一致，建议后端保持语义一致性 - 该功能从 Nginx 1.13.12 开始正式支持，旧版本需升级
验证是否生效
可通过日志或响应头确认效果：
- 查看
$upstream_cache_status：首次 HEAD 请求应为MISSED（因需先缓存 GET），后续同 URL 的 HEAD 应为HIT - 用
curl -I发送 HEAD 请求，观察是否返回缓存命中头（如X-Cache-Status: HIT）且无后端延迟 - 检查缓存目录下是否生成对应 key 的文件（含完整 GET 响应数据）
