用 watchEffect 实现系统版本自动检测与刷新提示,核心是监听远程 version.json 文件中 version 字段变化,在构建版本号与远程不一致时触发顶部横幅提示并支持立即刷新;通过防抖、可见性判断、时间戳参数及 CDN 缓存控制确保精准高效。

用 watchEffect 实现系统版本自动检测与刷新提示,核心是监听远程版本号变化,并在不一致时触发友好提示——它比手动轮询更精准,比 watch 更简洁,特别适合部署后前端资源未及时更新的场景。
监听远程 version.json 文件变化
将构建时写入的版本标识(如 commit hash 或语义化版本)暴露为静态资源,例如 /version.json:
在 Vue 组合式 API 中,用 watchEffect 主动发起请求并建立响应式依赖:
import { watchEffect } from 'vue'
import { useMessage } from '@/hooks/useMessage'
export function useAutoRefresh() {
const message = useMessage()
let currentVersion = __APP_VERSION__ // 构建时注入,如 via vite define
watchEffect(async (onInvalidate) => {
let latestVersion = ''
const controller = new AbortController()
onInvalidate(() => controller.abort())
try {
const res = await fetch('/version.json?_t=' + Date.now(), {
cache: 'no-cache',
signal: controller.signal
})
const data = await res.json()
latestVersion = data.version
if (latestVersion && latestVersion !== currentVersion) {
message.warn('检测到新版本,建议刷新页面以获取最新功能', {
showClose: true,
duration: 0,
onClose: () => location.reload()
})
}
} catch (e) {
// 请求失败不中断,静默忽略(如离线、404)
}
}, {
flush: 'post' // 确保 DOM 更新后执行,避免竞态
})
}
控制检测频率与时机
watchEffect 默认响应式执行,但版本检测不需要高频轮询。实际运维中应结合用户行为优化:
- 只在页面可见(
document.visibilityState === 'visible')时激活请求 - 添加防抖逻辑:用
setTimeout+onInvalidate清除,例如 5 分钟检查一次 - 跳过开发环境:
if (import.meta.env.DEV) return - 首次加载后延迟 3s 开始(避开白屏期),后续每次成功后间隔 10 分钟再查
处理缓存与 CDN 干扰
CDN 或浏览器可能缓存 /version.json,导致检测失效:
- 服务端设置
Cache-Control: no-store或极短 max-age(如 10s) - 客户端加时间戳参数(如示例中的
_t)确保 URL 唯一 - 避免使用
fetch(..., { cache: 'force-cache' })—— 必须绕过缓存 - 若用 Nginx,可配置
location /version.json { add_header Cache-Control "no-cache"; }
提示交互与用户体验细节
单纯弹窗易被忽略或打断操作,生产环境建议:
- 顶部常驻横幅(非模态),显示「✅ 已有新版本」+「立即刷新」按钮
- 点击刷新前先
localStorage.setItem('skipVersionCheck', Date.now()),防止重复提示 - 支持「稍后提醒」:定时器 30 分钟后再次检查
- 对 PWA 应用,检测到新版后可调用
workbox.messageSW({ type: 'SKIP_WAITING' })配合更新

















