配置 nginx 缓存版本号失效的核心做法是结合 `proxy_cache_key` 中的变量与 `proxy_cache_valid` 指令,通过 url 路径或请求参数携带版本标识来实现。当静态资源更新时,只需改变文件名(如 `style.v2.css`)或查询字符串(如 `app.js?v=2`),nginx 就会将其视为新的缓存键并重新获取源站内容,从而绕过旧缓存。

如何基于 URL 路径实现文件版本化
在 URL 路径中直接嵌入版本号是最常见的做法,例如将 `/static/style.css` 改为 `/static/v1/style.css`。这种方式的优点是缓存键天然包含版本信息,无需额外配置复杂的正则匹配。Nginx 会根据完整的 URI 生成不同的缓存文件,旧版本的缓存会因不再被访问而最终过期或被清理。

server {
listen 80;
server_name example.com;
# 定义缓存区域和路径
proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m;
location /static/ {
# 关键:将 $uri 加入缓存键,确保不同路径的文件独立缓存
proxy_cache_key "$scheme$proxy_host$request_uri";
# 启用缓存
proxy_cache my_cache;
# 设置缓存有效期,例如成功响应缓存 10 分钟
proxy_cache_valid 200 10m;
# 代理到后端或本地文件系统
root /var/www/html;
try_files $uri $uri/ =404;
}
}
在上述配置中,`proxy_cache_key` 使用了 `$request_uri`,这意味着 `/static/v1/style.css` 和 `/static/v2/style.css` 会被视为两个完全不同的资源。当部署新版本时,前端引用指向新路径,Nginx 自动拉取新文件并存入缓存。旧文件 `/static/v1/style.css` 的缓存条目不会立即删除,但也不会再被命中,直到达到 `inactive` 设定的超时时间后被自动清理。
如何通过查询参数控制缓存失效
如果不想修改文件路径,可以通过 URL 查询参数(Query String)来传递版本号,例如 `style.css?v=2`。这种方式需要确保 `proxy_cache_key` 包含 `$query_string`,否则 Nginx 可能会忽略参数差异而返回相同的缓存内容。此外,需配合 `proxy_cache_bypass` 或 `proxy_no_cache` 处理非版本化请求,避免缓存污染。

server {
listen 80;
server_name example.com;
proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m;
location ~* ^.+\.(css|js)$ {
# 关键:必须包含 $query_string,否则 ?v=1 和 ?v=2 会命中同一缓存
proxy_cache_key "$scheme$proxy_host$request_uri$is_args$args";
proxy_cache my_cache;
proxy_cache_valid 200 10m;
# 可选:如果希望某些请求不缓存,可以添加 bypass 逻辑
# proxy_cache_bypass $http_cache_control;
root /var/www/html;
try_files $uri =404;
}
}
此配置中,`$is_args$args` 确保了查询参数被完整纳入缓存键。当用户访问 `style.css?v=1` 时,Nginx 缓存该版本;当发布新版本并更新链接为 `style.css?v=2` 时,Nginx 发现新的缓存键,向源站发起请求并缓存新内容。需要注意的是,如果源站本身不支持版本化参数,需在 Nginx 层剥离参数后转发给源站,或使用 `proxy_set_header` 调整请求头,但缓存键仍需保留参数以区分版本。
缓存键冲突时如何处理相同内容的不同版本
当使用查询参数版本化时,若未正确配置 `proxy_cache_key`,可能导致不同版本的资源命中同一缓存条目,造成版本混乱。例如,若 `proxy_cache_key` 仅使用 `$request_uri` 而不包含 `$args`,则 `file.css?v=1` 和 `file.css?v=2` 可能被视为相同 URI,导致缓存覆盖或错误返回。解决此问题的关键是确保缓存键的唯一性,并验证实际缓存行为。
# 测试脚本:验证不同查询参数的缓存命中情况 # 假设 Nginx 已按上述配置运行 # 第一次请求,带版本 v1 curl -I http://example.com/style.css?v=1 # 预期结果:HTTP/1.1 200 OK, X-Cache-Status: MISS (首次加载) # 第二次请求,同样带版本 v1 curl -I http://example.com/style.css?v=1 # 预期结果:HTTP/1.1 200 OK, X-Cache-Status: HIT (命中缓存) # 第三次请求,带新版本 v2 curl -I http://example.com/style.css?v=2 # 预期结果:HTTP/1.1 200 OK, X-Cache-Status: MISS (新缓存键,重新获取) # 第四次请求,再次访问 v1 curl -I http://example.com/style.css?v=1 # 预期结果:HTTP/1.1 200 OK, X-Cache-Status: HIT (仍命中 v1 的缓存)
通过上述测试,可以确认 `proxy_cache_key` 中包含 `$args` 时,不同查询参数的请求会生成独立的缓存条目。若发现 `X-Cache-Status` 始终为 HIT 或 MISS 不符合预期,需检查 `proxy_cache_key` 是否遗漏了 `$args` 或 `$query_string`。此外,可通过 `proxy_cache_use_stale` 指令在源站不可用时提供 stale 缓存,但需注意 stale 缓存的版本一致性,避免返回过期的旧版本内容。











