Nginx协商缓存的实现

一、引言：被低估的“第二道防线”

在谈论浏览器缓存时，90%的文章都在讲强制缓存（max-age、immutable）。这没错，强制缓存是性能的天花板。但有一个残酷的现实：强制缓存不可能覆盖所有资源。

HTML入口文件不能强缓存，否则发版后用户永远看到旧页面；API响应不能强缓存，否则数据实时性无法保证；Service Worker脚本不能强缓存，否则应用无法自我更新；甚至某些不带内容哈希的遗留静态资源，也不敢贸然设置长过期时间。

在这些场景中，协商缓存（Conditional Caching）就是那道不可或缺的安全网。它通过一次轻量级的HTTP往返（304 Not Modified），在“数据新鲜度”和“传输效率”之间取得了精确平衡。然而在实际项目中，协商缓存常常被错误配置：要么ETag生成策略不合理导致验证永远失败，要么忽略了Vary头导致CDN返回错误版本，要么误以为no-cache等于不缓存而放弃了本可复用的本地副本。

本文将从HTTP协议底层出发，结合Nginx实现机制与现代前端工程化实践，帮你彻底掌握协商缓存的正确用法。

二、核心原理：条件请求的完整生命周期

2.1 什么是协商缓存？

协商缓存是指浏览器在本地副本过期（或未设置强制缓存）后，向服务器发起条件请求，由服务器判断资源是否变更：未变更则返回304（无响应体），变更则返回200+新内容。

它与强制缓存的本质区别：协商缓存一定会产生一次网络往返，但这次往返的代价远低于完整传输。

2.2 两套验证机制

📌 关键认知：浏览器优先使用ETag验证。当两者同时存在时，If-None-Match 优先级高于 If-Modified-Since。不要手动关闭任何一个，双保险是最安全的策略——ETag提供精确性，Last-Modified作为降级兜底。

2.3 304响应的严格约束

根据RFC 7232，304响应必须不包含消息体，且必须包含以下头部（如果原始200响应中包含的话）：

• Cache-Control / Expires
• ETag
• Content-Location
• Vary

这意味着304不仅是“省带宽”，它还承担着刷新本地缓存元数据的职责。浏览器收到304后会更新本地副本的过期时间和验证器，为下一次缓存决策做准备。

2.4no-cache≠ 不缓存

这是协商缓存中最普遍的误解：

⚠️ no-cache 是协商缓存的最佳搭档。它允许浏览器保留本地副本，只是要求每次使用前走一遍304验证流程。对于HTML等需要即时更新但又希望减少完整传输的资源，no-cache 比 no-store 高效得多。

三、Nginx协商缓存的实现机制

3.1 ETag的默认生成算法

Nginx对静态文件默认生成弱ETag，格式为：

W/"文件大小十六进制-修改时间十六进制"

例如：W/"1a2b3c-5f8e9d0a1b2c0"

这个算法的特点是：

• 零IO开销：仅需 stat() 系统调用获取文件大小和mtime，不需要读取文件内容；
• 天然版本一致：只要文件内容和修改时间不变，ETag就不变；
• CI/CD友好：如果部署流程保留了文件的原始mtime（如rsync -t、tar --preserve），ETag在多实例间天然一致。

⚠️ 注意：如果你的部署工具会重置mtime（如scp、某些Docker COPY操作），ETag将在每次部署后变化，导致304命中率骤降。此时应考虑改用基于文件内容的强ETag，或在部署流程中保留mtime。

3.2 Last-Modified的精度限制

Last-Modified的精度为秒级。如果一个文件在同一秒内被修改了两次（极端场景），第二次修改不会被检测到。这在现代构建工具中几乎不会发生（构建产物都是全新文件），但在动态生成的资源中需要注意。

3.3 动态内容的协商缓存

对于反向代理的后端响应，Nginx不会自动生成ETag。你需要在后端应用中自行实现ETag生成逻辑，或使用Nginx的第三方模块（如ngx_http_etag_filter_module增强版）。

一个常见的后端ETag策略是对响应体做MD5/SHA256哈希：

# Python Flask示例
import hashlib
from flask import make_response
@app.route('/api/config')
def get_config():
    data = get_latest_config()
    body = json.dumps(data)
    etag = hashlib.md5(body.encode()).hexdigest()
    response = make_response(body)
    response.headers['ETag'] = f'"{etag}"'
    response.headers['Cache-Control'] = 'no-cache'
    return response

四、Nginx协商缓存配置实战

4.1 HTML入口文件：协商缓存的经典场景

location ~* \.html?$ {
    # 禁止强制缓存，但允许存储本地副本
    add_header Cache-Control "no-cache, must-revalidate";
    # 确保协商缓存验证器开启（Nginx默认开启，显式声明防误关）
    etag on;
    last_modified on;
    # 防止后端覆盖缓存头
    proxy_hide_header Cache-Control;
}

工作流程：

1. 首次访问：200 + HTML内容 + ETag + Last-Modified → 浏览器存储副本
2. 再次访问：浏览器发送 If-None-Match + If-Modified-Since
3. 未发版：Nginx返回304 → 浏览器复用本地HTML（仅一次轻量往返）
4. 已发版：Nginx返回200 + 新HTML → 浏览器更新副本，加载新版JS/CSS

4.2 Service Worker脚本：必须协商缓存

location = /sw.js {
    add_header Cache-Control "no-cache, must-revalidate";
    etag on;
    # SW文件通常很小，Last-Modified兜底即可
}

⚠️ 绝对不能对sw.js设置强制缓存。浏览器发现新SW的唯一方式就是通过HTTP协商缓存检测到文件变更。如果sw.js被强缓存，应用将永远无法更新。

4.3 API响应的协商缓存模板

location /api/ {
    proxy_pass http://backend;
    # 透传后端的ETag和Cache-Control
    proxy_pass_header ETag;
    proxy_pass_header Cache-Control;
    # 如果后端未设置缓存头，提供兜底策略
    # 注意：仅在proxy_hide_header清除后端头后才需要add_header兜底
}

4.4 四个易踩坑的配置细节

① Vary头决定协商缓存的正确性

如果同一URL根据请求头返回不同内容（如gzip/brotli压缩、Accept-Language多语言），必须添加Vary头：

gzip on;
add_header Vary "Accept-Encoding";  # ⭐ 开启压缩时必加

否则CDN可能将gzip版本的ETag缓存后，用非gzip请求验证时得到304，却返回了gzip内容给不支持压缩的客户端→乱码。

②add_header继承陷阱再强调

# ❌ 子location中的add_header会导致父级Cache-Control丢失
server {
    add_header Cache-Control "no-cache";
    location /app/ {
        add_header X-Frame-Options "DENY";  # Cache-Control没了！
    }
}
# ✅ 每个location显式设置所有需要的头
location /app/ {
    add_header Cache-Control "no-cache, must-revalidate";
    add_header X-Frame-Options "DENY";
}

③always参数确保错误响应也有缓存头

# 不加always：4xx/5xx响应不会携带Cache-Control
add_header Cache-Control "no-cache" always;  # ✅ 所有状态码都生效

这对于API接口尤为重要——401/403响应如果被浏览器意外缓存，会导致后续合法请求也失败。

④ 避免ETag与Content-Encoding冲突

Nginx在gzip压缩后会自动重新计算ETag（变为弱ETag）。如果你在后端生成了基于原始内容的强ETag，经过Nginx压缩后会变成不同的弱ETag，导致浏览器验证失败。解决方案：

• 让后端生成弱ETag（W/"..."），Nginx压缩后保持一致；
• 或在Nginx层统一生成ETag，后端不设ETag。

五、调试与验证工具箱

5.1 Chrome DevTools诊断

5.2 curl命令行验证

# 1. 获取初始ETag
ETAG=$(curl -sI https://example.com/index.html | grep -i etag | awk '{print $2}' | tr -d '\r')
echo "ETag: $ETAG"
# 2. 模拟条件请求
curl -sI -H "If-None-Match: $ETAG" https://example.com/index.html
# 期望：HTTP/1.1 304 Not Modified
# 3. 验证Vary头
curl -sI -H "Accept-Encoding: gzip" https://example.com/style.css | grep -i vary
# 期望：Vary: Accept-Encoding
# 4. 检查304响应体是否为空
curl -s -o /dev/null -w "%{size_download}" -H "If-None-Match: $ETAG" https://example.com/index.html
# 期望：0（或极小的头部字节数）

5.3 监控304命中率

# 自定义日志格式，记录缓存状态
log_format cache_log '$remote_addr - $status - $upstream_cache_status - $request_uri';
# 分析304比例
awk '$3 == 304' access.log | wc -l

对于HTML和SW等资源，304占比应在60%~90%之间。过低说明验证器不稳定，过高（接近100%）可能意味着资源从未真正更新过。

六、常见踩坑速查表

七、结语

到此这篇关于Nginx协商缓存的实现的文章就介绍到这了,更多相关Nginx协商缓存内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！