我发布了前端新版本,可一大批用户死活还是旧页面、改的 bug 在他们那儿没修复,我对着 HTTP 缓存的 Cache-Control 排查了大半天的复盘

那是我做的一个 Web 项目。我修了个明显的前端 bug,打包、发布、上线,自己刷新一看好了。可没过多久,客服那边炸了:一大批用户反馈,那个 bug 在他们那儿还在、页面还是旧的;我让他们刷新,有的刷了也没用,直到"清缓存"或"强制刷新"才好。我一脸困惑:我明明发布了新版本啊,服务器上都是新代码了,用户怎么还在用旧的?我反复确认服务器上确实是新文件。排查了大半天,我才真正理解了 HTTP 缓存的门道,以及我那个"没配好 Cache-Control"的疏忽——它让用户的浏览器,一直在用着早就过期的旧缓存。这篇就把这场"发布了却更新不生效"的事故,从头复盘一遍。

故障现场:服务器是新的,用户却用旧缓存

先看现场。新版本发了,但用户被缓存"卡"在了旧版本:

# 现象: 发布前端新版本后, 大批用户还是旧页面
# - 服务器上确实是新文件(我确认过)。
# - 但用户的浏览器, 加载的还是【缓存里的旧文件】。
# - 普通刷新可能还是旧的, 强制刷新(Ctrl+F5)/清缓存才是新的。

# 我的服务器对静态文件(js/css/html)的缓存配置(问题所在):
#   - 我给所有静态资源都配了很长的缓存:
#     Cache-Control: max-age=31536000   (缓存1年!)
#   - 而且 js/css 文件名是固定的(如 app.js, 没有版本号/hash)。

# 为什么用户更新不了?
# 1. 第一次访问: 浏览器下载 app.js, 因为 Cache-Control: max-age=31536000,
#    浏览器把它缓存起来, 并认为"这个文件1年内都不用再请求了"。
# 2. 我发布了新版本: 服务器上的 app.js 变成了新内容。
# 3. 但用户再访问时: 浏览器一看"app.js 我缓存了, 还没过期(1年呢)",
#    → 【根本不向服务器请求】, 直接用本地缓存的旧 app.js!
#    → 用户看到的还是旧页面、旧bug。
# 4. 文件名又是固定的(app.js), 所以浏览器认为"还是那个文件", 命中旧缓存。
# 5. 只有强制刷新/清缓存, 浏览器才会重新去服务器拿 → 才看到新的。

# 现象拼图:
#   - 我给固定文件名的静态资源, 配了超长缓存(max-age=1年)。
#   - 浏览器在缓存有效期内, 根本不会再向服务器请求, 直接用旧缓存。
#   - 文件名没变(app.js), 浏览器认不出"这是新文件" → 一直用旧的。
#   - ★ 根因: "长缓存"和"固定文件名"的组合 —— 既让浏览器长期不请求,
#     又让它无法识别文件已更新, 于是用户被永久卡在旧版本(直到缓存过期/清缓存)。

看清真相后,我才明白这"发了却不生效"的根子。问题的根源,是我给静态资源配置缓存的方式有问题:我给所有静态资源都配了超长缓存(Cache-Control: max-age=31536000,1 年),而 js/css 文件名又是固定的(app.js,没有版本号/hash)。于是:第一次访问浏览器下载并缓存了 app.js、认为"1 年内不用再请求";我发布新版本后,用户再访问时浏览器一看"app.js 我缓存了还没过期",就根本不向服务器请求、直接用本地缓存的旧 app.js;而文件名又没变(还是 app.js),浏览器认为"还是那个文件"、命中旧缓存;只有强制刷新/清缓存才会重新拿。根因是:"长缓存"和"固定文件名"的组合——既让浏览器长期不请求,又让它无法识别文件已更新,于是用户被永久卡在旧版本(直到缓存过期/清缓存)。

第一件事:搞懂 HTTP 缓存的机制

要解决它,得先彻底搞懂 HTTP 缓存的机制——强缓存和协商缓存。

HTTP 缓存机制: 强缓存 + 协商缓存

# 一、为什么要有缓存?
#   - 让浏览器/CDN 把资源存起来, 下次直接用, 不用每次都向服务器请求。
#   - 好处: 快(本地就有)、省流量、减轻服务器压力。
#   - 但代价: 资源更新了, 缓存可能还是旧的(本文的坑)。

# 二、强缓存(Cache-Control / Expires): "缓存期内根本不请求服务器"
#   - Cache-Control: max-age=N → 资源缓存N秒, 这期间浏览器【直接用缓存】,
#     【完全不向服务器发请求】(连"问一下变没变"都不问)。
#   - 所以: 强缓存期内, 即使服务器更新了, 浏览器也不知道、还用旧的(本文)。
#   - Cache-Control: no-cache → 每次都要先问服务器(走协商缓存)。
#   - Cache-Control: no-store → 完全不缓存(每次都重新下载)。

# 三、协商缓存(ETag / Last-Modified): "每次问服务器:变了吗?"
#   - 浏览器请求时带上 ETag(资源的"指纹")或 Last-Modified(修改时间)。
#   - 服务器比对: 没变 → 返回 304 Not Modified(不传内容, 浏览器用缓存, 省流量)。
#                变了 → 返回 200 + 新内容。
#   - 好处: 既能缓存(没变就用旧的, 省流量), 又能及时更新(变了就拿新的)。
#   - 代价: 每次都要发一个请求去"问"(有网络往返, 但比传整个文件快)。

# 四、关键: 强缓存 vs 协商缓存怎么选?
#   - 强缓存(max-age): 性能最好(连请求都不发), 但更新不及时。
#   - 协商缓存(no-cache+ETag): 更新及时, 但每次都有个请求往返。
#   - 经典策略(见正解): 对"带hash的静态资源"用强缓存(长), 对"HTML入口"
#     用协商缓存(每次问), 两者配合, 既快又能更新。

# 核心: HTTP缓存分强缓存(max-age, 缓存期内不请求服务器、更新不及时)和协商缓存
#   (ETag/Last-Modified, 每次问服务器变没变、304复用、更新及时); 要按资源类型搭配使用。

想透 HTTP 缓存机制,这个坑就清楚了。一、为什么要有缓存?——让浏览器/CDN 存起来下次直接用,快、省流量、减轻服务器压力;但代价是资源更新了缓存可能还是旧的(本文)。二、强缓存(Cache-Control/Expires):"缓存期内根本不请求服务器"——max-age=N 资源缓存 N 秒、这期间浏览器直接用缓存、完全不发请求(连"问一下变没变"都不问),所以强缓存期内即使服务器更新了浏览器也不知道、还用旧的(本文);no-cache 每次都先问服务器、no-store 完全不缓存。三、协商缓存(ETag/Last-Modified):"每次问服务器:变了吗?"——请求带上 ETag(指纹)或 Last-Modified,服务器比对:没变返回 304(不传内容、用缓存、省流量),变了返回 200+新内容;既能缓存又能及时更新,代价是每次有个请求往返。四、强缓存 vs 协商缓存怎么选?——强缓存性能最好但更新不及时,协商缓存更新及时但每次有请求往返;经典策略是对"带 hash 的静态资源"用强缓存(长)、对"HTML 入口"用协商缓存(每次问),配合使用既快又能更新。

第二件事:正解——文件名带 hash + 分类型设缓存

搞懂了原理,正解就清晰了:给静态资源文件名带内容 hash(内容变文件名就变)、HTML 入口用协商缓存/不缓存、按资源类型分别设缓存策略。

# ====== 正解一(核心): 静态资源文件名带"内容 hash" ======
# 让构建工具(webpack/vite等)给文件名加上"内容指纹":
#   app.js     →  app.3f8a2b1c.js   (文件名里含内容hash)
#   style.css  →  style.9d4e7f.css
# - 文件内容【没变】→ hash不变 → 文件名不变 → 命中缓存(快)。
# - 文件内容【变了】→ hash变 → 文件名变 → 浏览器认为是"新文件", 重新下载!
# - 这样: 既能给这些文件配【超长强缓存】(因为内容变了文件名就变, 不怕缓存旧的),
#   又能在更新时让用户立刻拿到新的(新文件名 = 新请求)。
# 配置: 带hash的静态资源 → Cache-Control: max-age=31536000, immutable
#   (immutable 告诉浏览器"这文件永不变", 连刷新都不重新请求, 极致性能)

# ====== 正解二(关键): HTML 入口文件用"协商缓存"或"不强缓存" ======
# HTML(index.html)是"入口", 它里面引用了那些带hash的js/css。
# - HTML 文件名是固定的(index.html, 不能带hash, 否则用户不知道访问哪个)。
# - 所以 HTML 要用: Cache-Control: no-cache (每次都问服务器, 走协商缓存)
#   或 max-age=0, must-revalidate。
# - 这样: 每次访问都拿到【最新的HTML】, 而最新HTML里引用的是【新hash的js/css】,
#   → 用户就能加载到新版本! (HTML不缓存/协商缓存 + 静态资源hash强缓存 = 完美)

# ====== 整体策略(经典且推荐)======
#   HTML(index.html):     no-cache (协商缓存, 每次拿最新)
#   带hash的js/css/图片:   max-age=31536000, immutable (超长强缓存)
#   不带hash的资源:        协商缓存(ETag), 或短缓存
#   API数据:              按需(实时数据no-store, 可缓存的设合理max-age)

# ====== 正解三(应急/补充): 给URL加版本号查询参数 ======
# 如果不方便改文件名(如第三方资源), 可在URL后加版本参数:
#   
# 改版本号 → URL变 → 浏览器当新资源请求。(不如hash优雅, 但能用)

# ====== 正解四: CDN 缓存也要一起考虑 ======
# - 资源往往还经过CDN缓存。发布新版本后, CDN可能还缓存着旧的。
# - 解决: 带hash的文件天然不冲突(新文件名CDN没缓存, 会回源拿);
#   HTML等要"刷新CDN缓存"(purge), 或给CDN配合适的缓存规则。

# ====== 正解五: 验证缓存配置 ======
# - 浏览器DevTools的Network面板: 看每个资源的Cache-Control响应头、
#   是否命中缓存(from disk cache / 304 / 200)。
# - 发布后, 确认HTML是新的(200/304拿到新的)、引用了新hash的资源。

# 核心: 静态资源文件名带内容hash(内容变名就变)+配超长强缓存immutable; HTML入口用no-cache
#   协商缓存(每次拿最新, 引到新hash资源); 别让"固定文件名+长强缓存"卡住用户; 注意CDN缓存。

修复的核心,是"用'文件名带 hash'让浏览器能识别文件更新,并按资源类型分别设缓存"。正解一(核心):静态资源文件名带"内容 hash"——让构建工具给文件名加内容指纹(app.js → app.3f8a2b1c.js):内容没变 hash 不变、文件名不变、命中缓存;内容变了 hash 变、文件名变、浏览器当"新文件"重新下载;这样既能给它配超长强缓存(内容变文件名就变、不怕缓存旧的),又能更新时让用户立刻拿到新的(配 max-age=31536000, immutable)。正解二(关键):HTML 入口用"协商缓存"或"不强缓存"——HTML 文件名固定(不能带 hash),用 no-cache 每次问服务器拿最新;而最新 HTML 里引用的是新 hash 的 js/css,用户就能加载到新版本(HTML 协商缓存 + 静态资源 hash 强缓存 = 完美)。正解三(应急):给 URL 加版本号查询参数(app.js?v=20260602,不如 hash 优雅但能用)。正解四:CDN 缓存也要一起考虑(带 hash 的文件天然不冲突,HTML 等要刷新 CDN 缓存)。正解五:用 DevTools 的 Network 面板验证缓存配置。归根结底:静态资源文件名带内容 hash + 配超长强缓存 immutable;HTML 入口用 no-cache 协商缓存;别让"固定文件名+长强缓存"卡住用户;注意 CDN 缓存。

第三件事:HTTP 缓存的其他常见坑

排查后我把 HTTP 缓存的其他常见坑也系统梳理了一遍。

HTTP 缓存的其他常见坑

# 1. 固定文件名 + 长强缓存(本文): 更新不生效。→ 文件名带hash。

# 2. 反过来: 该缓存的没缓存, 每次都回源:
#    - 静态资源没配缓存(或no-store)→ 每次都重新下载, 慢、费流量、压服务器。
#    → 给"不常变的静态资源"配合理的缓存。

# 3. HTML配了强缓存(致命!):
#    - 如果连index.html都配了长max-age, 那用户连"新的HTML"都拿不到,
#      → 永远进不去新版本(比静态资源更新不了还严重)。
#    → HTML 永远别配长强缓存, 用no-cache/协商缓存。

# 4. API数据该不该缓存搞错:
#    - 实时/会变的API数据配了缓存 → 用户看到旧数据。→ no-store/no-cache。
#    - 不怎么变的(如配置/字典)可以配短缓存, 减轻服务器压力。

# 5. 缓存了带个人信息的响应(隐私问题):
#    - 含用户私密数据的响应被(共享)缓存 → 可能泄漏给别人。
#    → 这类响应用 Cache-Control: private(只允许浏览器缓存, 不允许CDN等共享缓存)
#      或 no-store。

# 6. Vary 头没配好:
#    - 同一URL根据请求头(如Accept-Encoding/语言)返回不同内容时,
#      要配 Vary 头, 否则缓存可能返回错误的版本。

# 7. 只信浏览器缓存, 忘了中间还有CDN/代理缓存:
#    - 缓存可能发生在多个层(浏览器、CDN、反向代理), 排查/刷新要都考虑。

# 核心: HTTP缓存坑还有 该缓存没缓存、HTML配强缓存(致命)、API缓存搞错、缓存隐私数据、
#   Vary没配、忘了CDN层; 核心是按资源类型配对策略(静态hash强缓存/HTML协商/API按需/隐私不缓存)。

排查让我把 HTTP 缓存的其他坑也梳理清了。一、固定文件名 + 长强缓存(本文)。二、反过来该缓存的没缓存(每次回源、慢费流量)。三、HTML 配了强缓存(致命!)——连新 HTML 都拿不到、永远进不去新版本,HTML 永远别配长强缓存。四、API 数据该不该缓存搞错(实时数据配缓存看到旧的、用 no-store)。五、缓存了带个人信息的响应(隐私问题)——用 Cache-Control: private 或 no-store。六、Vary 头没配好(同 URL 不同内容要配 Vary)。七、只信浏览器缓存、忘了 CDN/代理缓存(缓存在多层,排查/刷新都要考虑)。它们的核心是:按资源类型配对策略(静态 hash 强缓存/HTML 协商/API 按需/隐私不缓存)。下面这张图,是这次发布后更新不生效的成因与解法:

第四件事:不同资源的缓存策略速查

这次踩坑后,我把不同类型资源该配什么缓存策略整理成一张表,配缓存时对照着来。

这张表,把"什么资源配什么缓存"讲清了。核心规律是:"内容会随更新而变、但文件名能变"的(带 hash 的静态资源)→ 长强缓存(最快);"文件名固定、必须拿最新"的(HTML)→ 协商缓存;"实时数据"→ 不缓存;"隐私数据"→ 不共享缓存。它给我的最大启发是:缓存不是"开"或"关"的二选一,而是要针对不同资源的"变化频率"和"更新需求",配不同强度的策略;"一刀切"(全部长缓存=本文的坑,或全部不缓存=性能差),都不对。这其实是一个普适的权衡思想:缓存的本质,是用"数据可能稍旧"换"访问更快";而"能容忍多旧",取决于数据的"变化频率和更新及时性要求"——变化慢、不要求实时的,可以多缓存(换性能);变化快、要求实时的,就少缓存或不缓存(保新鲜)。所以配缓存的关键,是对每一类资源,想清楚它"多久变一次、更新要多及时",再据此选择"缓存多久"——这种"按数据特性差异化配置"的思路,远比"一刀切"更能兼顾性能和正确性。

第五件事:缓存的"双刃剑"本质

这次事故让我对缓存这把"双刃剑"有了更立体的认识。我把它的两面整理了一下。

这张表,把缓存这把"双刃剑"的两面摊开了。缓存的好处(快、省)无需多言,但它的代价同样真实:可能拿到旧数据、缓存和源不一致、"为什么还是旧的"很难查(因为缓存可能在浏览器、CDN、代理多层)、以及最核心的难题——怎么让缓存及时失效。它给我的最大启发是:缓存,是一个典型的"用一致性换性能"的权衡;它通过"持有一份数据的副本"来加速,但这份副本一旦和源头不同步,就产生了"旧数据"问题——而"如何让缓存及时失效、保持和源一致",正是缓存领域最难的问题之一(那句著名的"计算机科学只有两件难事:缓存失效和命名"就是说这个)。我这次踩的坑,本质就是"缓存失效"没做好:我让浏览器缓存了静态资源,却没设计好"资源更新后,怎么让这个缓存失效、让用户拿到新的"(文件名带 hash 正是解决缓存失效的优雅方案)。这让我领悟到:每当我引入缓存来提升性能时,都必须同时、认真地设计好它的"失效策略":数据更新后,这个缓存怎么知道自己该失效了?怎么让使用者拿到新的?——"只加缓存、不管失效",几乎必然会在某天因为"用户拿到旧数据"而出问题。引入缓存,就要为它的"失效"负责到底。

第六件事:配置资源缓存时,我现在的决策习惯

现在每当我要给一个资源配缓存,我都会按这张图先想清楚它的变化特性和更新需求:

这张图的精髓,是"配缓存前,先想清楚资源的更新特性和及时性要求"。第一问 "这资源会更新吗、更新要多及时":内容会变但能带 hash 的(静态资源)→ 文件名带 hash + 超长强缓存;入口/必须每次拿最新的(HTML)→ no-cache 协商缓存;实时数据(API)→ no-store;不常变可容忍稍旧的 → 协商缓存或短缓存。含隐私的还要加 private(别让 CDN 等共享缓存)。最后一步是我现在的硬习惯:发布后用 DevTools 验证缓存命中和更新生效(这次的坑正是因为发布后没验证用户拿到的是不是新版本)。这套习惯,让我配缓存时,从"图省事全配长缓存"变成了"按资源特性差异化配置并验证"——核心始终是:缓存要按资源的更新特性配,静态资源 hash+强缓存、HTML 协商缓存、实时数据不缓存,并设计好失效。

我立下的几条规矩

这场"发布后更新不生效"的事故,换来了我做 Web 缓存时,刻进骨子里的几条铁律:

1. 静态资源文件名带内容 hash。内容变文件名就变,这样才能既长缓存又能更新。
2. 带 hash 的静态资源配超长强缓存。max-age=1年 + immutable,又快又不怕缓存旧的。
3. HTML 入口永远别配长强缓存。用 no-cache 协商缓存,每次拿最新(否则永远进不去新版本)。
4. 实时 API 数据 no-store。不能缓存,否则用户看到旧数据。
5. 含隐私的响应用 private 或 no-store。防被共享缓存泄漏给别人。
6. 别忘了 CDN/代理层缓存。缓存在多层,发布后该刷的要刷、排查要全考虑。
7. 发布后验证更新生效。用 DevTools 确认用户拿到的是新版本,别只看服务器。

附:一套正确的前端缓存配置(Nginx + 构建)

口说无凭。下面给一套可直接用的前端缓存配置:构建产物带 hash,Nginx 按类型分别设缓存:

# ============ 1. 构建配置: 产物文件名带 hash(以 Vite 为例)============
# vite.config.js / webpack: 默认就会给产物加 hash:
#   build: { rollupOptions: { output: {
#     entryFileNames: 'assets/[name].[hash].js',     // app.3f8a2b1c.js
#     chunkFileNames: 'assets/[name].[hash].js',
#     assetFileNames: 'assets/[name].[hash].[ext]',  // style.9d4e7f.css
#   }}}
# → 构建出来: index.html(固定名) 引用 assets/app.3f8a2b1c.js(带hash)

# ============ 2. Nginx 配置: 按资源类型设缓存 ============
server {
    root /var/www/dist;

    # --- HTML: 不强缓存, 每次协商(确保拿到最新HTML, 引到新hash资源)---
    location = /index.html {
        add_header Cache-Control "no-cache";   # 每次问服务器(协商缓存)
        # 或更严: "no-cache, no-store, must-revalidate";
    }

    # --- 带hash的静态资源: 超长强缓存 + immutable ---
    location /assets/ {
        # 这些文件名带hash, 内容变文件名就变, 所以可以放心长缓存
        add_header Cache-Control "public, max-age=31536000, immutable";
        # max-age=31536000 = 1年; immutable = 连刷新都不重新请求
    }

    # --- 其他静态资源(不带hash的, 如favicon): 中等缓存 ---
    location ~* \.(ico|png|jpg|svg)$ {
        add_header Cache-Control "public, max-age=86400";  # 1天
    }

    # SPA 路由: 找不到的路径都返回 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }
}

# ============ 3. 发布后验证(浏览器DevTools Network面板)============
# - 访问页面, 看 index.html 的响应: Cache-Control: no-cache, 且是新内容。
# - 看 app.[hash].js: Cache-Control 含 immutable; 二次访问应 from cache。
# - 发新版本后: index.html 拿到新的(引用了新hash的js) → 用户加载新版本。
#   旧的 app.[oldhash].js 不再被引用(新HTML里是新hash), 自然淘汰。

# 核心: 构建产物带hash + Nginx对HTML设no-cache(协商, 拿最新)、对带hash资源设
#   max-age=1年+immutable(超长强缓存); 发布即生效又长期缓存; DevTools验证。

这套配置,把这篇文章的解法,落成了可以直接抄用的前端缓存方案。它由两部分协同:构建阶段让产物文件名带 hash(内容变文件名就变);Nginx 阶段对 HTML 设 no-cache(协商缓存,每次拿最新)、对带 hash 的静态资源设 max-age=31536000, immutable(超长强缓存)。这套组合的精妙之处在于,它同时拿到了"性能"和"及时更新"两个看似矛盾的好处:静态资源(占了大头的 js/css)享受着"一年强缓存、连请求都不发"的极致性能;而每次发布,只要 HTML(它很小、且协商缓存)拿到了新的、引用了新 hash 的资源,用户就能立刻加载到新版本。"变的部分(HTML)不缓存,不变的部分(带 hash 的资源)永久缓存"——通过"用文件名 hash 把'变'和'不变'区分开",巧妙地化解了"性能"和"更新"的矛盾。这,正是我想用这套配置,留给每个做 Web 的人的最后一课:很多看似"鱼和熊掌不可兼得"的矛盾(这里是"缓存的性能"和"更新的及时"),往往可以通过一个巧妙的设计(文件名带 hash)而两者兼得;而这种"化解矛盾的巧思",通常来自于对问题本质的深刻理解(理解了"缓存失效的关键是让浏览器识别文件已变",就想到了"用文件名携带内容指纹"这个妙招)。遇到看似两难的权衡,别急着妥协,先深入理解问题的本质,常常能找到那个"既要又要"的优雅解法——这,是我从这场缓存事故里,带走的最有价值的思维方式。

写在最后

回头看,这场由"HTTP 缓存配置不当"引发的、发布后更新不生效的事故,真正教给我的,远不止"文件名带 hash"这一个技巧。它让我对"性能优化的副作用"有了更深刻的体会。缓存,是一个我们为了"性能"而引入的优化;我配上长缓存,本意是好的(让页面加载更快、减轻服务器压力)。可这个为了"快"的优化,却带来了一个我没预料到的副作用——"用户更新不了"。我只看到了缓存"让访问变快"的正面,却忽略了它"会让数据变旧"的反面。这让我领悟到一个关于"优化"的深刻道理:几乎每一个"优化",都不是纯粹的好处,而是一个"权衡(trade-off)"——它在改善某个方面(性能)的同时,往往会牺牲或损害另一个方面(这里是数据的新鲜度/一致性);而如果你只盯着它带来的好处、没有同时考虑并管理好它带来的代价,这个"优化"就可能从"提升"变成"故障"。缓存如此(快 vs 旧),索引如此(查快 vs 写慢),长连接如此(复用 vs 维护),冗余如此(性能 vs 一致性)……每一项优化技术,都带着它自己的"代价标签"。所以,这件事给我的最大警示是:每当我引入一个"优化"时,都要主动、清醒地问一句:"这个优化,在带来好处的同时,牺牲了什么?我有没有把那个'被牺牲的方面'管理好?";对缓存,就是"我提升了性能,但有没有管好'缓存失效',确保数据该新的时候能新?"。看清优化的代价、并管理好它——这,是我用一次"更新不生效"的事故,换来的、关于网络、也关于"优化即权衡"的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次配前端缓存时,用上"文件名 hash + HTML 协商缓存"这套组合,那我对着那一批死活更新不了的用户熬的这大半天,就值了。

—— 别看了 · 2026