ja-web-version-update-checker

一个独立、无外部依赖的前端版本更新提示器。同时兼容 Webpack 和 Vite。

该包提供了一个高颜值的 UI 组件，用于在系统发布新版本时，在右下角优雅地提示用户刷新页面。其原理是在打包（build）阶段自动生成一个 version.json，并在浏览器运行时在后台静默轮询对比版本差异。

核心特性

• 框架无关：完美兼容 Vue、React 或是原生 JavaScript 项目。
• 开箱即用的构建插件：内置了 Webpack 和 Vite 两种构建工具的专属插件。
• 零外部依赖：基于原生 JavaScript 和原生 DOM API 实现，无需引入 Element UI、Ant Design 或 Axios。
• 高颜值 UI：自带平滑的滑入滑出动画、悬浮光影交互，并支持 light (浅色) 与 dark (深色科技风) 双主题。
• 性能友好：在后台静默轮询，结合 visibilitychange 事件，仅在用户可见活跃状态时触发版本对比。

安装

npm install ja-web-version-update-checker --save

快速上手

1. 注入构建插件（生成版本文件）

如果你使用 Webpack (如 Vue CLI 架构)

在您的 vue.config.js 或 webpack.config.js 中：

const WebpackVersionPlugin = require('ja-web-version-update-checker/src/webpack-plugin');

module.exports = {
  configureWebpack: config => {
    // 建议仅在生产或测试环境下开启
    if (process.env.NODE_ENV === "production" || process.env.NODE_ENV === "test") {
      config.plugins.push(new WebpackVersionPlugin());
    }
  }
}

如果你使用 Vite

在您的 vite.config.js 中：

import { defineConfig } from 'vite';
import ViteVersionPlugin from 'ja-web-version-update-checker/src/vite-plugin';

export default defineConfig({
  plugins: [
    ViteVersionPlugin()
  ]
});

2. 初始化运行时（监听版本更新）

在您应用的总入口文件（例如 main.js 或 index.js）中引入并启动它：

import { startVersionCheck } from 'ja-web-version-update-checker';

// 建议仅在生产或测试环境下开启
if (process.env.NODE_ENV === 'production' || process.env.NODE_ENV === 'test') {
  startVersionCheck({
    publicPath: process.env.BASE_URL || '/', // 请确保此处与您项目打包的 publicPath 一致
    pollingInterval: 5, // 每 5 分钟轮询一次
    theme: 'dark' // 可选 'dark' (深色) 或 'light' (浅色)
  });
}

配置项 (Options)

startVersionCheck 支持传入以下参数对象：

| 属性名 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | publicPath | String | / | 项目部署的基准路径，用于寻找 version.json 的准确位置。 | | pollingInterval | Number | 5 | 轮询服务端版本号的时间间隔（单位：分钟）。 | | theme | String | 'dark' | 弹窗的 UI 主题，目前支持 'dark' 和 'light'。 | | title | String | '🎉 系统更新提示' | 弹窗标题文字，可按需自定义。 | | description | String | '系统发布了新版本...' | 弹窗的主体描述内容，可按需自定义。 | | buttonText | String | '✨ 立即刷新体验' | 刷新按钮的文字，可按需自定义。 |

License

MIT