前端发版后用户不刷新两套极简方案搞定无感更新提醒文章目录前端发版后用户不刷新两套极简方案搞定无感更新提醒一、 为什么 HTML Hash 轮询是首选方案二、 方案 1原生 JavaScript 极简封装带健壮性增强项目入口调用Vue 3 / React1. version.json 里面存的是什么2. 它明明是文件为什么能像“接口”一样被请求到它是怎么被访问到的3. 这个文件是怎么自动生成的方式 A在 Vite 项目中通过简单配置生成vite.config.js方式 B如果你使用插件 plugin-web-update-notification三、 方案 2开箱即用 plugin-web-update-notification 插件1. 安装依赖2. Vite 配置 (vite.config.js)四、 关键运维配置必须禁用 index.html 缓存五、 方案选型与技术总结六、 WebSocket 最适合的 5 大场景当前场景不适合1. 实时互动与社交IM 聊天 / 直播2. 多人协作与实时看板在线文档 / 画板3. 金融与高频数据变化股票 / 加密货币4. 实时游戏网页端联机游戏5. 物联网IoT与设备状态监控总结在现代单页应用SPA开发中一个常见且棘手的问题是代码更新部署上线后用户仍保留在旧页面中操作。这不仅会导致新功能无法体验还容易引发新旧接口不兼容、静态资源加载报错ChunkLoadError甚至提交脏数据。今天就来聊聊目前行业中最主流、最轻量的解决方案基于index.html的 Script Hash 轮询检测并奉上原生封装与自动化插件两套落地实践。一、 为什么 HTML Hash 轮询是首选方案在考虑更新提醒时不少开发者会想到WebSocket或Service Worker但在“版本更新检测”这一特定场景下它们的性价比并不高WebSocket适合高频、低延迟的双向实时通信如 IM 聊天、协同文档、股市行情。但对于几天或几周才发版一次的系统维持成千上万个长连接会导致极高的服务器内存与运维成本。Service Worker离线能力强大但缓存控制与更新生命周期极为繁琐稍有不慎就会引发“强缓存清除不掉”的线上灾难。相比之下基于index.html的 Script Hash 轮询方案优势极其明显零后端改造成本纯前端 Nginx 现有静态托管即可。绝对准确现代打包工具Vite / Webpack每次构建都会生成带唯一 Hash 的静态文件名注入index.html。极低开销仅拉取极小体积的 HTML 字符串配合策略触发对服务器压力几乎为零。[ 1. 页面加载记录初始 Hash ] ──► [ 2. 定时/切页请求最新 index.html ] │ [ 4. 变化即触发更新提醒 ] ◄─── [ 3. 提取 Script Hash 比对 ]二、 方案 1原生 JavaScript 极简封装带健壮性增强如果不想引入额外依赖可以用几十行纯 JS 代码封装一个更新检测器。为了避免“频繁弹窗扰民”和“并发请求过度”我们在基础轮询上补全了防抖锁、连续两次确认防 CDN 抖动与Session 级打扰拦截细节// auto-updater.jsexportclassAutoUpdater{constructor(options{}){this.checkIntervaloptions.checkInterval||5*60*1000;// 默认 5 分钟this.onUpdateoptions.onUpdate||((){});this.oldScriptsnull;this.timernull;this.isCheckingfalse;// 请求并发锁this.diffCount0;// 连续不一致计数器防 CDN 节点未同步抖动}// 1. 获取并提取 index.html 中所有 script 的 src 路径asyncgetScripts(){try{consthtmlawait(awaitfetch(/?t${Date.now()})).text();constreg/script[^]src[]([^])[]/g;returnArray.from(html.matchAll(reg),mm[1]);}catch{return[];}}// 2. 执行 Hash 比对与防抖逻辑asynccheck(){// 防打扰若用户在此 Session 中点过“稍后提醒”本次会话不再弹窗if(sessionStorage.getItem(dismiss_update_notice)true)return;if(this.isChecking)return;this.isCheckingtrue;constnewScriptsawaitthis.getScripts();this.isCheckingfalse;if(!newScripts.length)return;if(!this.oldScripts){this.oldScriptsnewScripts;return;}// 比对 Script Hash 列表if(JSON.stringify(this.oldScripts)!JSON.stringify(newScripts)){this.diffCount;// 连续 2 次检测到变化才确认更新避免 CDN 边缘节点发布同步延迟造成的误报if(this.diffCount2){this.onUpdate();this.stop();}}else{this.diffCount0;// 恢复正常}}// 3. 开启多维度监听start(){this.check();// 策略 A定时轮询this.timersetInterval(()this.check(),this.checkInterval);// 策略 B页面重新获得焦点/切回标签页时立即检测性价比最高时机this.handleVisibility(){if(document.visibilityStatevisible)this.check();};document.addEventListener(visibilitychange,this.handleVisibility);}stop(){clearInterval(this.timer);document.removeEventListener(visibilitychange,this.handleVisibility);}}项目入口调用Vue 3 / React// main.jsimport{AutoUpdater}from./auto-updater;constupdaternewAutoUpdater({onUpdate:(){// 可替换为 Element Plus / Ant Design 的 Modal 组件if(confirm(系统检测到新版本是否立即刷新页面以获得最新功能)){window.location.reload();}else{// 用户选择稍后记录 sessionStorage避免后续轮询继续弹窗扰民sessionStorage.setItem(dismiss_update_notice,true);}}});updater.start();// 隐藏防御策略捕获旧 Chunk 缺失报错自动强制刷新兜底window.addEventListener(error,(event){if(event?.message?.includes(Loading chunk)||event?.message?.includes(Failed to fetch dynamically imported module)){window.location.reload();}},true);1.version.json里面存的是什么它里面通常只放几行最简单的 JSON 文本包含版本号、构建时间戳或Git Commit ID。例如打包时生成的public/version.json内容如下{version:1.2.0,buildTime:1718000000000,commitId:a1b2c3d4}2. 它明明是文件为什么能像“接口”一样被请求到在 Web 开发中“接口”和“静态文件”在 HTTP 协议的底层本质上是一样的——它们都是浏览器向服务器发起的 HTTP GET 请求服务器接收到请求后返回一段文本内容。它是怎么被访问到的当你把项目打包如执行npm run build后version.json会被放在打包产物的根目录即dist/目录下。当你的网站部署到服务器比如 Nginx后访问网站页面浏览器请求[https://yourdomain.com/](https://yourdomain.com/)Nginx 返回dist/index.html访问静态文件浏览器请求[https://yourdomain.com/version.json](https://yourdomain.com/version.json)Nginx 会在dist/目录下找到这个文件直接把文件里的 JSON 字符串返回给前端。因此你在前端 JS 代码里直接写// 就像请求普通 API 接口一样 fetch 静态文件fetch(/version.json?tDate.now()).then(resres.json()).then(data{console.log(服务器上的最新版本,data.version);});浏览器就会收到标准状态码200 OK并拿到 JSON 数据3. 这个文件是怎么自动生成的你不需要每次发布都手动去修改这个文件通常由打包工具自动生成方式 A在 Vite 项目中通过简单配置生成vite.config.js利用 Vite 的自定义插件钩子在打包时写一个文件到dist目录// vite.config.jsimport{defineConfig}fromvite;importfsfromnode:fs;importpathfromnode:path;// 自定义一个极简生成 version.json 的插件functioncreateVersionJsonPlugin(){return{name:create-version-json,closeBundle(){constversionData{version:process.env.npm_package_version||1.0.0,buildTime:Date.now()};// 打包完成后自动在 dist 目录生成 version.jsonfs.writeFileSync(path.resolve(__dirname,dist/version.json),JSON.stringify(versionData,null,2));}};}exportdefaultdefineConfig({plugins:[createVersionJsonPlugin()]});方式 B如果你使用插件plugin-web-update-notification这个插件在打包时也会自动在你的根目录下生成一个隐藏的json格式的版本标记文件并在后台用fetch去请求它原理完全一样三、 方案 2开箱即用 plugin-web-update-notification 插件如果你使用Vite或Webpack脚手架推荐使用社区成熟插件plugin-web-update-notification/vite。它在构建打包时会自动生成version.json并在后台静默比对零业务代码侵入。1. 安装依赖npminstallplugin-web-update-notification/vite-D2. Vite 配置 (vite.config.js)import{defineConfig}fromvite;import{webUpdateNotice}fromplugin-web-update-notification/vite;exportdefaultdefineConfig({plugins:[webUpdateNotice({checkInterval:5*60*1000,// 轮询间隔 (ms)默认 10 分钟checkOnWindowFocus:true,// 窗口恢复焦点时主动检测checkImmediately:true,// 页面加载完成后立即检测// 配置 UI Toast 弹窗文案notificationProps:{title: 系统更新提醒,description:检测到新版本上线请刷新页面以使用最新功能。,buttonText:立即刷新,dismissButtonText:稍后提醒,},}),],});四、 关键运维配置必须禁用index.html缓存特别注意无论选择哪种检测方案服务器或 CDN 侧必须对index.html设置协商缓存或禁用强缓存如果浏览器直接强缓存了index.html前端轮询拿到的始终是本地旧文件检测逻辑将彻底失效。# nginx.conf server { listen 80; server_name example.com; location / { try_files $uri $uri/ /index.html; # 核心配置对 html 文件禁用强缓存 if ($request_filename ~* .*\.(html)$) { add_header Cache-Control no-cache, no-store, must-revalidate; add_header Pragma no-cache; add_header Expires 0; } } # 带打包 Hash 的静态资源js/css可放心开启长效强缓存 location /assets/ { expires 1y; add_header Cache-Control public, immutable; } }五、 方案选型与技术总结维度方案 1原生 JS Hash 轮询方案 2plugin-web-update-notification代码侵入性极低仅需引入一个 30 行工具类零代码侵入纯构建插件配置UI 自定义完全自由轻松对接项目中现有 UI 组件库内置 Toast 弹窗也支持自定义 UI构建脚手架限制通用Vite, Webpack, Rollup 均可主要适配 Vite / Webpack / Umi 等工程兜底能力需手写ChunkLoadError监听与体验锁插件内置完整生命周期与提示拦截推荐指数⭐⭐⭐⭐适合有自定义 UI 需求的团队⭐⭐⭐⭐⭐适合追求开箱即用的工程六、 WebSocket 最适合的 5 大场景当前场景不适合WebSocket 的最大优势是建立一次 TCP 连接后服务器可以主动向客户端推送数据且数据包头极小、延迟极低。1. 实时互动与社交IM 聊天 / 直播场景微信 Web 版、飞书/钉钉网页版、直播间弹幕、在线客服。原因消息需要毫秒级送达且客户端和服务端都在高频发送数据。2. 多人协作与实时看板在线文档 / 画板场景腾讯文档、Figma、Kanban 任务看板、协同代码编辑器。原因需要实时同步多个用户的光标位置、输入内容或拖拽状态保证“所见即所得”。3. 金融与高频数据变化股票 / 加密货币场景炒股软件、加密货币交易所如 Binan/Coinbase的 K 线图与深度图。原因价格每秒都在剧烈变动HTTP 轮询会导致大量的 Header 开销和网络拥堵而 WebSocket 传输效率极高。4. 实时游戏网页端联机游戏场景Web 端的各种联机对战游戏、棋牌游戏。原因对延迟RTT有极高要求必须持续维持双向低延迟数据流。5. 物联网IoT与设备状态监控场景智慧园区、工业大屏、设备实时温度/运行状态监控。原因传感器数据需要实时上报并在大屏上动态渲染。总结对于绝大部分企业 Web 系统采用“HTML Hash 轮询 visibilitychange 页面唤醒 ChunkLoadError 兜底 Nginx 禁缓存”是目前开发成本最低、用户体验最好、线上最稳健的无感更新提醒实践。 感谢阅读想了解更多 我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目
郑州网站建设
网页设计
企业官网
![完全免费！跨平台图表绘制神器draw.io桌面版终极指南 [特殊字符]](http://pic.xiahunao.cn/yaotu/完全免费！跨平台图表绘制神器draw.io桌面版终极指南 [特殊字符])
![[具身智能-181]：PC+服务器+具身机器人：构建具身智能从仿真到量产的闭环迭代混合架构](http://pic.xiahunao.cn/yaotu/[具身智能-181]：PC+服务器+具身机器人：构建具身智能从仿真到量产的闭环迭代混合架构)
![[具身智能-181]：大分布式通信模型对比：看懂为什么 DDS 是 ROS2 底层通信最优解](http://pic.xiahunao.cn/yaotu/[具身智能-181]：大分布式通信模型对比：看懂为什么 DDS 是 ROS2 底层通信最优解)
