version-check

前端版本更新检测：构建期生成 version.json 并注入版本号，运行在路由切换（或自定义时机）时拉取远端元信息比对；发现新版本时可用整页刷新落到用户目标路由，避免 SPA 热更新遗漏。

本包将 vite、vue、vue-router 声明为可选 peer：只用核心 API 时可不装；使用 version-check/vite 或 version-check/vue 时请在项目中安装对应依赖（版本需与你的工程一致）。

组成

| 入口 | 说明 | | -------------------- | ----------------------------------------------------------------------------------------------------------- | | version-check | createVersionChecker()：框架无关，在任意时机调用 check() | | version-check/vite | versionCheckPlugin()：写入 version.json、define 注入、HTML 内联 window.__APP_VERSION__、dev 中间件 | | version-check/vue | installVersionGuard(router)：在 Vue Router beforeEach 中节流检查，差异时 location.href 强刷到目标 URL |

推荐：Vite + Vue

// vite.config.ts
import { defineConfig } from "vite";
import { versionCheckPlugin } from "version-check/vite";

export default defineConfig({
  plugins: [
    versionCheckPlugin({
      version: process.env.CI_BUILD_ID ?? undefined, // 缺省为构建时间戳
      meta: { env: process.env.NODE_ENV },
    }),
  ],
});

// router.ts
import { createRouter } from "vue-router";
import { installVersionGuard } from "version-check/vue";

const router = createRouter({
  /* ... */
});

installVersionGuard(router, {
  throttle: 30_000,
  beforeReload: (diff) => {
    console.log("新版本:", diff.latest);
  },
});

export default router;

子路径部署时请将 createVersionChecker / 守卫的 url 设为带 base 的完整地址（例如与 import.meta.env.BASE_URL 拼接），默认仅为 /version.json。

仅核心（非 Vue）

import { createVersionChecker } from "version-check";

const checker = createVersionChecker({ url: "/version.json", debug: true });
const diff = await checker.check();
if (diff) {
  window.location.reload();
}

部署注意

• 将产物根目录的 version.json 配为 短时缓存或 no-cache，否则 CDN 长期缓存会导致永远读旧版本、误判或漏判。
• 插件在 dev 下会注册中间件提供 GET /version.json，避免本地 404。

API 摘要

• createVersionChecker(options?)：check() 返回 VersionDiff | null；失败或版本一致返回 null，不抛错。
• versionCheckPlugin(options?)：可配置 filename、injectName、version、meta、debug。
• installVersionGuard(router, options?)：在 VersionCheckerOptions 基础上支持 throttle、beforeReload（返回 false 可取消强刷）。

类型见包内导出：VersionInfo、VersionDiff、VersionChecker、VersionCheckerOptions、VersionGuardOptions、VitePluginOptions。

环境

• Node.js：见 package.json 的 engines.node（当前 ≥ 22.21.1）。

License

ISC