从“甩锅”到“兜底”，一套代码实现缓存自愈，把用户体验拉回 100 分
一、为什么“清缓存”成了技术圈的梗？
“老师，页面白屏了！”
“清下浏览器缓存试试。”
—— 这段对话每天都在各家公司重复上演。
用户不会理解「缓存」是什么，他们只会觉得“你们网站又出 Bug 了”。
更尴尬的是，90% 的线上“旧代码”问题，确实只靠强制刷新就能解决。
于是前端背锅，用户流失，产品经理发飙。
根源
- 静态资源走「强缓存」（Cache-Control/Expires），服务器都收不到请求。
index.html本身也被缓存，导致chunk-vite-abc123.js404 却没人知道。- 发版窗口没做「灰度 + 版本兜底」，一挂全挂。
目标
让用户永远不再看到旧代码，同时永远不再听到“清缓存”三个字。
二、先给缓存“把个脉”：浏览器到底缓存了谁？
| 缓存位置 | 谁控制 | 典型场景 | 是否可 JS 感知 |
|---|---|---|---|
| Memory Cache | 浏览器 | 同一会话后退/刷新 | ❌ |
| Disk Cache (HTTP 缓存) | Response Header | 强缓存 200(from disk) | ❌ |
| Service Worker Cache | 开发者代码 | PWA 离线包 | ✅ |
| Push Cache | HTTP/2 | 已废弃 | ❌ |
结论
只有 Service Worker 能让前端“自己管自己”，其余都无法在出错时主动清理。
因此「让用户清缓存」本质是把不可控因素甩给用户——极不专业。
三、设计思路：把“发版”做成“自愈”
- 版本号 → 可对比
每次 CI 在全局注入__APP_VERSION__ = '1.2.3-beta.1+202509211100' - 服务器 → 永远返回最新
index.html（Cache-Control: no-cache） - 前端 → 轮询版本号，发现不一致即主动 reload并跳过缓存
- 兜底 → 若 JS 抛错 404，同样触发 reload
- 灰度 → 只有带
?v=latest的 5% 流量走新版本，出错自动回滚
四、代码落地（Vue3 + Vite 为例，React/Angular 同理）
1. CI 注入版本
# .github/workflows/release.yml
echo "export const APP_VERSION = '${GITHUB_REF_NAME}+$(date +%Y%m%d%H%M)';" > src/meta/version.js
vite.config.ts
import { defineConfig } from 'vite'
import { APP_VERSION } from './src/meta/version'
export default defineConfig({
define: {
__APP_VERSION__: JSON.stringify(APP_VERSION),
},
})
2. 版本轮询模块（src/core/version-guard.ts）
const VERSION_CHECK_INTERVAL = 60_000 // 1min
const RETRY_MAX = 3
async function fetchMeta() {
// 加 search 防止自身被缓存
const res = await fetch('/meta.json?t=' + Date.now())
return res.json() as Promise<{ version: string }>
}
export function startVersionGuard() {
let retry = 0
const loop = async () => {
try {
const { version } = await fetchMeta()
if (version !== __APP_VERSION__) {
// 发现新版本
const event = new CustomEvent('sw-update', { detail: { version } })
window.dispatchEvent(event)
// 立即刷新，skipWaiting 效果
location.reload()
} else {
retry = 0
}
} catch (e) {
if (++retry >= RETRY_MAX && import.meta.env.PROD) {
// 可能 index.html 都是旧的，强制硬刷新
location.href = location.href + '?v=' + Date.now()
}
}
}
setInterval(loop, VERSION_CHECK_INTERVAL)
loop() // 立即执行一次
}
3. 404 兜底（src/core/error-tracker.ts）
window.addEventListener('error', (e) => {
const src = e.filename ?? ''
if (/chunk-.*\.js$/.test(src) && e.message.includes('Failed to fetch')) {
// 旧 chunk 404
sessionStorage.setItem('force-reflow', '1')
location.href = location.href + '?v=' + Date.now()
}
})
4. index.html 永不缓存
location = /index.html {
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
5. 资源文件长期缓存 + 内容哈希
// vite 默认 chunk-[hash].js，确保文件名一变就 404，触发兜底
build.rollupOptions.output.entryFileNames = 'static/js/[name]-[hash].js'
五、灰度 & 回滚：把“爆炸半径”缩到最小
- 边缘层（CDN/Nginx）按 Cookie 或 Query 分流
if ($arg_v = latest) { proxy_pass http://new-bucket; } - 前端报错统一上报 Sentry，1 分钟错误率 > 0.2% 自动回滚（CI 调用 CDN 回源接口切流）
- 用户侧：版本不一致时先弹柔性提示“检测到新版本，3 秒后自动刷新”，避免突兀。
六、最终效果
- 发版后 60s 内，所有在线用户静默切换到最新代码。
- 用户本地缓存的
chunk-abc123.js404 → 自动硬刷新，零人工介入。 - 客服再也没收到“页面空白”的工单。
- 产品经理主动在群里点赞：“最近怎么没人报 bug 了？”
七、常见疑问 Q&A
Q1. 轮询不会增加服务器压力吗？
/meta.json 只有 200B，1 分钟一次，1 万日活一天才 1k×60×24 ≈ 1.4M 请求，静态文件 CDN 0.01 元/万次，成本忽略不计。
Q2. 移动端后台标签长时间不刷新怎么办？
监听 visibilitychange，切回前台立即检查版本；再配合 Service Worker 的 clients.claim() 可瞬间激活新代码。
Q3. 企业内网无法联网，怎么更新？
内网场景建议把 index.html 做成 no-cache，发版通知用户刷新当前页即可；其余资源仍走哈希缓存，平衡速度与可靠性。
八、结语：把“清缓存”写进历史
“清缓存”本质是把技术债转嫁给用户。
只要做到：
- 版本可感知
- 入口文件无缓存
- 旧资源 404 能兜底
- 灰度可回滚
就能让发版像“热更新”一样丝滑。
下次再有人让你“清缓存”，请把这篇博客甩给他，并温柔地说：
“不用，我们网站自己会洗澡。”
