设计目的
为了解决前端项目部署之后,如何通知用户系统有新版本,并引导用户刷新页面以加载最新资源的问题。
适用场景
用户在浏览器中打开某 web 应用(通常是后台管理系统)很长时间且未刷新页面时,如果应用有新功能添加或问题修复,用户可能无法及时知道有新版发布。这样会导致用户继续使用旧版,影响用户体验和数据准确性,甚至出现程序报错。
实现原理
- 使用
Web Worker
API 在浏览器后台轮询请求页面,不会影响主线程运行。 - 命中协商缓存,对比本地和服务器请求响应头
etag
字段值。 - 如果
etag
值不一致,说明有更新,则弹出更新提示,并引导用户手动刷新页面(例如弹窗提示),完成应用更新。 - 当页面不可见时(例如切换标签页或最小化窗口),停止实时检测任务;再次可见时(例如切换回标签页或还原窗口),恢复实时检测任务。
- 在本地 localStorage存入 APP_ETAG, 当etag值不一致时表示有新的版本,弹出更新提示框,同时更新本地存储的etag值
安装使用
js
npm install version-polling --save
使用
这里只提供npm 依赖构建用法,也可以通过 script 引入,直接插入到 HTML
js
// 在应用入口文件中使用: 如 main.js, app.jsx
import { createVersionPolling } from "version-polling";
createVersionPolling({
appETagKey: "__APP_ETAG__",
pollingInterval: 5 * 60 * 1000, // 单位为毫秒-默认5分钟轮询一次
silent: process.env.NODE_ENV === "development", // 开发环境下不检测
onUpdate: (self) => {
// 当检测到有新版本时,执行的回调函数,可以在这里提示用户刷新页面
const result = confirm("页面有更新,点击确定刷新页面!");
if (result) {
self.onRefresh();
} else {
self.onCancel();
}
// 强制更新可以用alert
// alert('有新版本,请刷新页面');
},
})
详细参数
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
appETagKey | web 应用更新唯一标识字段名 | string | APP_ETAG |
pollingInterval | 轮询间隔,单位为毫秒,默认为 5 分钟 | number | 5 * 60 * 1000 |
immediate | 初始化后, 立即触发实时监测 | boolean | true |
htmlFileUrl | web 应用网站运行目录 | string | {location.origin}{location.pathname} |
silent | 初始化后, 立即触发实时监测 | boolean | true |
onUpdate | 更新检测的回调函数,可以自定义更新的逻辑 | (self) => void | - |