企业官网建设流程全解析

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

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

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

根源

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

目标

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

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

结论

只有 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.ymlecho"export const APP_VERSION = '${GITHUB_REF_NAME}+$(date+%Y%m%d%H%M)';">src/meta/version.js

// vite.config.tsimport{defineConfig}from'vite'import{APP_VERSION}from'./src/meta/version'exportdefaultdefineConfig({define:{__APP_VERSION__:JSON.stringify(APP_VERSION),},})

2. 版本轮询模块（src/core/version-guard.ts）

constVERSION_CHECK_INTERVAL=60_000// 1minconstRETRY_MAX=3asyncfunctionfetchMeta(){// 加 search 防止自身被缓存constres=awaitfetch('/meta.json?t='+Date.now())returnres.json()asPromise<{version:string}>}exportfunctionstartVersionGuard(){letretry=0constloop=async()=>{try{const{version}=awaitfetchMeta()if(version!==__APP_VERSION__){// 发现新版本constevent=newCustomEvent('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)=>{constsrc=e.filename??''if(/chunk-.*\.js$/.test(src)&&e.message.includes('Failed to fetch')){// 旧 chunk 404sessionStorage.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.js 404 → 自动硬刷新，零人工介入。
• 客服再也没收到“页面空白”的工单。
• 产品经理主动在群里点赞：“最近怎么没人报 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 能兜底
• 灰度可回滚

就能让发版像“热更新”一样丝滑。
下次再有人让你“清缓存”，请把这篇博客甩给他，并温柔地说：
“不用，我们网站自己会洗澡。”