别再让用户“清缓存”了！前端缓存策略的“自解”方案全解析

zhenglin

2026年5月6日 16:33 本文热度 68

从“甩锅”到“兜底”，一套代码实现缓存自愈，把用户体验拉回 100 分

一、为什么“清缓存”成了技术圈的梗？

“老师，页面白屏了！”
“清下浏览器缓存试试。”
—— 这段对话每天都在各家公司重复上演。
用户不会理解「缓存」是什么，他们只会觉得“你们网站又出 Bug 了”。
更尴尬的是，90% 的线上“旧代码”问题，确实只靠强制刷新就能解决。
于是前端背锅，用户流失，产品经理发飙。

根源

静态资源走「强缓存」（Cache-Control/Expires），服务器都收不到请求。
index.html 本身也被缓存，导致 chunk-vite-abc123.js 404 却没人知道。
发版窗口没做「灰度 + 版本兜底」，一挂全挂。

目标
让用户永远不再看到旧代码，同时永远不再听到“清缓存”三个字。

二、先给缓存“把个脉”：浏览器到底缓存了谁？

缓存位置	谁控制	典型场景	是否可 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 秒后自动刷新”，避免突兀。