update-monitoring

通过比对 index.html 中引用的 JS/CSS 资源 URL 的哈希总和，检测前端是否有新版本发布。

特性

• 支持 Vue 2 / Vue 3
• 轮询检查（仅页面可见时生效）
• 页面隐藏时停止检测（不再发起检测请求）
• 可选：路由跳转后额外检查（页面可见时触发一次 check）
• 从隐藏切回可见时：立刻执行一次检查
• 支持手动 check()

安装

npm install update-monitoring

回调参数（newVersion / oldVersion / isUpdate）

更新结果通过 onUpdate(newVersion, oldVersion, isUpdate) 返回：

onUpdate(newVersion, oldVersion, isUpdate)

• newVersion：本次检查计算出的版本哈希（字符串）
• oldVersion：会话基线版本哈希（首次通常为 ""；首次成功后会固定为基线，直到页面刷新）
• isUpdate：是否检测到“有待刷新”（oldVersion !== "" && newVersion !== oldVersion）。只要服务器指纹与基线不同，后续轮询会持续为 true，直到页面刷新。

所有配置参数有哪些

1) UpdateMonitorOptions（核心配置）

interface UpdateMonitorOptions {
  indexUrl?: string; // 入口 HTML 地址；不填时会自动推导（优先 `<base href>`，否则 `location.origin + '/'`）

  interval?: number; // 前台轮询间隔(ms)；默认 10000

  enabled?: boolean; // 是否启动自动检查（定时 + 切回可见触发）；默认 true

  onUpdate?: (newVersion: string, oldVersion: string, isUpdate: boolean) => void;
}

说明（重要）：

• 当 document.hidden === true 时：会停止轮询，并且 check() 不会发起检测请求。
• 当 document.hidden 从 true 变为 false 时：会立刻执行一次检查。

2) Vue 插件额外配置（开启路由跳转触发）

当你希望在“路由跳转完成后立即检查更新”时，需要把 router 传给 UpdateMonitorPlugin：

router?: {
  afterEach: (guard: () => void) => () => void;
}

不传 router 时：路由跳转不会额外触发 check()；只靠 interval 和“切回可见”触发。

配置示例（Vue2 / Vue3 一样的参数）

Vue 3（createApp().use(...)）

import { createApp } from "vue";
import router from "./router";
import App from "./App.vue";
import { UpdateMonitorPlugin } from "update-monitoring";

const app = createApp(App);

// 关键：想在 main 里调用控制器方法，需要在 use 之后拿到 controller
let monitor: any;

app.use(router);
app.use(UpdateMonitorPlugin, {
  interval: 3 * 1000,
  enabled: true,
  router,

  onUpdate(newVersion, oldVersion, isUpdate) {
    if (!isUpdate) return;
    console.log("检测到新版本", { newVersion, oldVersion });

    // 示例：在 main 的 onUpdate 里调用控制器方法
    monitor?.setEnabled(false);
  },
});

monitor = app.config.globalProperties.$updateMonitor;

app.mount("#app");

在 Vue 3 里也可以用 Composition API 调用控制器方法（inject）：

import { inject, onMounted } from "vue";
import type { UpdateMonitorController } from "update-monitoring";

const monitor = inject<UpdateMonitorController>("updateMonitor");

onMounted(() => {
  // 页面可见时生效；页面 hidden 时不会触发请求
  void monitor?.check();
});

Vue 2（Vue.use(...)）

import Vue from "vue";
import router from "./router";
import App from "./App.vue";
import { UpdateMonitorPlugin } from "update-monitoring";

Vue.use(UpdateMonitorPlugin, {
  interval: 3 * 1000,
  enabled: true,
  router,

  onUpdate(newVersion, oldVersion, isUpdate) {
    if (!isUpdate) return;
    console.log("检测到新版本", { newVersion, oldVersion });
  },
});

new Vue({
  router,
  render: (h) => h(App),
}).$mount("#app");

Vue 2 Options API 里调用控制器方法：

export default {
  mounted() {
    // 页面可见时生效
    this.$updateMonitor?.check();

    // 暂停/继续
    // this.$updateMonitor?.setEnabled(false);
    // this.$updateMonitor?.setEnabled(true);
  },
};

直接使用（非 Vue，手动创建控制器）

import { createUpdateMonitor } from "update-monitoring";

const monitor = createUpdateMonitor({
  interval: 10_000,
  enabled: true,
  onUpdate(newVersion, oldVersion, isUpdate) {
    // ...
  },
});

// 手动立即检查一次（页面隐藏时不会触发）
void monitor.check();

控制器方法（createUpdateMonitor 返回）

• check()：手动立即检查一次（页面 hidden 时无检测请求）
• start()：启动自动检查
• stop()：停止自动检查定时器
• setEnabled(boolean)：动态开关自动检查
• getEnabled()：读取当前是否允许自动检查
• isRunning()：是否已 start
• destroy()：销毁监听与定时器