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

根源

1. 静态资源走「强缓存」（Cache-Control/Expires），服务器都收不到请求。

2. index.html 本身也被缓存，导致 chunk-vite-abc123.js 404 却没人知道。

3. 发版窗口没做「灰度 + 版本兜底」，一挂全挂。

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

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

结论：
只有 Service Worker 能让前端“自己管自己”，其余都无法在出错时主动清理。
因此「让用户清缓存」本质是把不可控因素甩给用户——极不专业。

# .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 { 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）

  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";
}

五、灰度 & 回滚：把“爆炸半径”缩到最小

1. 边缘层（CDN/Nginx）按 Cookie 或 Query 分流

   if ($arg_v = latest) { proxy_pass http://new-bucket; }

2. ​前端报错统一上报 Sentry，1 分钟错误率 > 0.2% 自动回滚（CI 调用 CDN 回源接口切流）

3. 用户侧：版本不一致时先弹柔性提示“检测到新版本，3 秒后自动刷新”，避免突兀。

六、最终效果

• 发版后 60s 内，所有在线用户静默切换到最新代码。

• 用户本地缓存的 chunk-abc123.js 404 → 自动硬刷新，零人工介入。

• 客服再也没收到“页面空白”的工单。

• 产品经理主动在群里点赞：“最近怎么没人报 bug 了？”