静态文件缓存改版就不生效:三层缓存、四种版本号做法与上线切换顺序

给静态文件加长缓存几乎是每个站长都会做的第一件事:在 Nginx 里写一条 expires 三十天,或者给 CDN 配一个缓存规则,然后看着 CDN 命中率从三成涨到九成,觉得很满意。但很少有人在下一次改版时回头看:那些带三十天缓存的 CSS 和 JS,改完之后有多少老用户还看着上一版?页面结构变了、样式没变,于是出现“排版错乱”“按钮没反应”这类投诉,而你自己在无痕窗口里怎么试都正常。

文件缓存这件事,真正的难点从来不是“怎么加上去”,而是“上线时怎么换掉”。这篇文章把缓存的三个层次、版本号失效的几种做法、以及上线后如何验证,按可以照着做的顺序讲一遍。全部基于 Nginx 与静态托管,不依赖任何框架的构建链路,个人站同样适用。

三层缓存各管一段:浏览器、中间层与本地磁盘

一个静态请求从访问者的浏览器到源站,中间至少经过三层缓存,每层的失效方式完全不同。混在一起讨论是绝大多数“改了没生效”问题的根源。

第一层是浏览器本地缓存。它由响应头里的 Cache-Control 和 Expires 决定,一旦存下来,在过期之前浏览器根本不会发出请求——连条件请求都不发,直接用自己的副本。所以这一层最省流量,但也最难清。你无法远程清除用户的浏览器缓存,只能靠改 URL 或者等它过期。

第二层是中间层,包括 CDN 节点和 Nginx 上的反向代理缓存。它看的是同一组响应头,加上自己的 TTL 配置。CDN 通常允许手动刷新,但刷新有延迟,而且部分节点可能没刷到。这也是为什么“刷了 CDN 还有人看到旧版”的原因之一——可能那个人命中的是本地浏览器缓存,根本不是 CDN。

第三层是源站磁盘缓存,比如 PHP 的 OPcache、或者 Nginx 的 fastcgi_cache。这一层的失效由文件修改时间和配置决定,通常不需要人工干预,但要注意 OPcache 的 revalidate 设置,关掉验证之后改文件不重启就不生效。

判断问题出在哪一层,最快的办法是看响应头里的 Age 和 X-Cache 之类字段。用 curl 带 -I 看一次,如果 Age 是一个较大的数,说明命中了中间层缓存;如果 Age 接近零而本地还是旧的,那就是浏览器缓存。这一步必须做,否则很容易把浏览器缓存误判成 CDN 没刷,白白浪费一轮操作。

为什么只加 expires 不够:时间值本身不是版本

很多人以为“缓存七天”就等于“七天内改动能生效”,其实刚好相反:七天是一个固定的窗口,在这七天里,改动对已经拿到旧文件的用户完全不生效。窗口越长,用户体验越差;窗口越短,缓存越没有意义。这是一个死结,仅靠调时间值解决不了。

结的解法只有一个:把“文件变了”这件事编码进 URL。URL 一换,浏览器和 CDN 都认为是全新的资源,不会再拿旧的副本。此时 Cache-Control 才能从一周安心地放到一年,因为你不打算让它在同一个 URL 上改变。

顺带说清楚两处常见的误区。第一,Expires 与 Cache-Control 同时出现时,现代浏览器以 Cache-Control 为准,Expires 只当兜底;两条都写且值不一致,会让某些中间缓存取错值,最好只留一条。第二,模板里 add_header 是“整组替换”而不是“追加”:在某个 location 里写了 add_header Cache-Control,就会把 server 层写的安全头一起顶掉。这是配置里最容易埋雷的地方,排查时要看 nginx -T 展开后的完整结果。

版本号的四种做法,以及各自的代价

把版本编码进 URL,有四种常见做法,从简单到严谨排列:

一、查询串版本号。在引用地址后面加问号加版本,例如样式表地址末尾跟一个 v 等于日期。改动时手工把日期换掉。优点是零成本、一眼能看懂;缺点是容易忘。一旦某次改版漏了更新这个数字,问题会静默发生——页面能开,只是样式是旧的。而且要人工记住哪些文件改了、改了哪几个。

二、文件修改时间自动拼入。让程序读取文件的 mtime 拼到地址后面。这解决了“忘改”的问题,成本是一点点文件系统调用。要注意两点:一是 mtime 在部署时如果被统一刷成同一时间(很多打包工具会这么做),所有文件的版本号会一起变,等于让全站缓存同时失效,那一波回源的流量会顶到源站;二是跨机器部署时 mtime 可能不一致,多地部署要留意。

三、内容哈希命名。文件名里带内容的摘要,例如主文件名后跟一段八位十六进制。文件内容不变则名字不变,内容一变名字必变,这是最严谨的一类。代价是需要构建步骤,而且被引用的地方必须全部同步——HTML 模板里、CSS 里引用的字体、JS 里动态拼接的图片地址,漏一处就是 404。

四、目录级版本。把整批静态资源放进一个带版本号的目录,HTML 统一指向新目录。实现最简单,代价是不能做细粒度缓存,一处小改动会让整目录失效。适合资源不多、更新频率低的小站。

四种做法没有绝对优劣。个人站通常用第二种,够用且不会忘;有一定发布流程的站点用第三种;只有一两个样式表的小站用第一种也完全可以,只要在发布清单里写上一行“记得改版本号”,并且真的检查。

响应头怎么写:资源和页面的寿命要相反

版本做对之后,响应头就变得简单而明确。静态资源可以放心长缓存,页面则必须短缓存,这两类不能写成同一套。

带版本指纹的静态资源,一年不变是安全的,同时加上 immutable 告诉浏览器“不要再去验证”:

location ~* \.(css|js|woff2|png|jpg|webp|avif|svg)$ {
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable";
    access_log off;
    try_files $uri =404;
}

注意 try_files 必须写,否则文件不存在时可能被后面的规则接管,返回一个 200 的 HTML 页面,浏览器把 HTML 当样式表解析,页面直接白屏,而日志里状态码是 200,非常难查。

HTML 页面则相反,要么不缓存,要么极短:

location ~* \.html$ {
    add_header Cache-Control "no-cache";
}

no-cache 不是“不缓存”,而是“可以存但每次都要回源验证”,配合 ETag 或 Last-Modified 就能变成 304,既保证内容最新,又不浪费带宽。真正不缓存要写 no-store,但那个对页面来说太狠,会连带影响前进后退的体验。

还有几类特殊的配置文件,寿命规则跟静态资源完全不是一回事:robots.txt 绝对不能长缓存,改坏了要等缓存过期才能恢复抓取;sitemap 最好短缓存;而站点图标和 manifest 可以给几天。把这些都塞进“静态资源一年”那条正则里,是典型的配置事故。

上线流程:先传资源、再改页面,最后清缓存

缓存做对之后,上线本身也需要有顺序。顺序错了,用户会看到“新旧混杂”的状态:HTML 是新版,引用的样式是新名字,但样式还没传上去,于是 404、白屏。

正确的顺序是三步。第一,先把所有新版静态资源上传,而且要用新名字(哈希或新版本号),旧文件暂时不要删。这一步上传完之后,新地址已经可以访问,但还没有任何页面指向它,所以对用户没有影响。第二,把 HTML 与模板切换到新地址并发布。此刻起,用户拿到的页面指向的资源全部已经存在。第三,观察一到两天,确认日志里旧文件名的请求已经降到接近零,再删旧文件。这个“先留旧文件”的动作几乎是零成本,却能挡住回滚和长尾用户两类问题。

如果静态资源和页面在同一个机器上,还要注意部署过程中的替换不是原子操作。正确做法是传到临时目录再整体重命名,而不是边传边覆盖。边传边覆盖的窗口期只有几秒,但正好在这几秒访问的用户会拿到半个文件——样式表前半截有效、后半截缺失,页面会呈现一种奇怪的部分生效状态,非常难复现。

回滚也要预先想好。最省事的回滚是“把旧版本目录重新指向”,而不是“把新文件改回旧内容”——后者要求你还保留着旧内容,而如果旧文件已经删了,就回不去了。所以旧版本的保存时间至少要覆盖观察期,不要发布完就清理。

验证:用三条命令确认缓存真的按预期工作

改完配置不能凭感觉。至少做三件事。

第一,看单个资源的响应头是否如预期。带 -I 请求两次,第二次应该有 Age 值增长、状态是 200 或 304:

curl -sI "https://www.example.com/static/main.8f3a1c.css" | grep -Ei 'cache-control|etag|age|expires'

第二,确认版本切换后老地址与新地址都能访问。老地址在过渡期必须还能打开,否则还在用旧页面的用户会看到白屏。这一步用两条 curl 各查一次状态码即可。

第三,抽样看访问日志里静态资源的状态码分布。如果某一类扩展名出现成片的 404,说明引用地址和实际文件对不上,最常见的原因是漏传了字体或图片。用一行命令按扩展名聚合:

awk '{print $7, $9}' /var/log/nginx/access.log \
  | grep -E '\.(css|js|woff2|png)$' \
  | awk '{print $1, $2}' | sort | uniq -c | sort -rn | head -20

另外,本地测试时务必用无痕窗口或加上禁用缓存的选项。用普通窗口测“缓存是否生效”,测到的往往是上一次的结果,这也是很多人反复怀疑配置没生效的来源。

几个容易忽略的边界

还有三处边界值得一并处理。第一是 WebView 与小程序环境:这类内置浏览器对 Cache-Control 的遵守程度不一致,部分实现会无视 no-cache 直接用自己的启发式缓存。对这种环境,版本号是唯一可靠的手段,不要指望响应头。第二是 Service Worker:一旦注册,它会接管静态资源的请求,你的 Nginx 配置对它无效。如果站点用了 Service Worker,更新逻辑必须单独设计,通常是让 SW 文件本身短缓存、并在里面主动清理旧缓存。第三是代理软件与运营商劫持:少数环境下中间设备会缓存 HTML,表现为“只有某个地区看到旧页面”,这种问题在响应头层面几乎无解,只能靠更频繁的版本变化与页面自身的时效标记来降低影响。

缓存是个人站性价比最高的优化之一,但它的收益全在“命中率”上,而它的风险全在“换不掉”上。把版本编码进 URL、资源和页面上线分两步走、验证时看清是哪一层在生效,这三件事做完,长缓存才敢真的开到一年。否则,你优化的从来不是速度,只是把一次改版变成一场猜谜。

Last modification:November 19th, 2026 at 10:31 pm

Leave a Comment