VersionChecker 检测网站更新

主要功能

一个用于 Vue 网站的智能版本检测插件，能够自动检测网站更新并提示用户刷新页面。

• 🚀 自动版本检测 - 轮询检查版本更新
• 📱 智能提示 - 检测到更新时自动提示用户
• ⚡ 灵活配置 - 支持自定义检测间隔和回调函数
• 🔧 多种使用方式 - 支持 Vue 插件方式和独立函数调用
• 🎯 精确状态反馈 - 提供详细的检测结果状态

使用方法

首先不管是哪种使用方式，都需要在打包构建时生成版本信息文件。可以通过引入 devecouiVersionPlugin 插件来来实现：

在我们的 vite.config.ts 文件中进行如下配置：

import { fileURLToPath, URL } from 'node:url'
import { defineConfig ,type Plugin} from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
import {devecouiVersionPlugin} from 'devecoui-plus/vite-plugin' // 只需要引入这两句

export default defineConfig({
  plugins: [
    vue(),
    vueDevTools(),
    devecouiVersionPlugin() as Plugin, // 只需要引入这两句
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    },
  }
})

作为 Vue 插件使用

import { createApp } from 'vue'
import App from './App.vue'
import { VersionChecker } from 'devecoui-plus/vite-plugin'

const app = createApp(App)

// 基本使用(使用默认配置)
app.use(VersionChecker)

// 进阶使用(自定义配置)
app.use(VersionChecker,{
    enableDetection:import.meta.env.PROD,// 线上环境开启 默认开启true
    interval:2000,// 默认2秒检测一次
    customPrompt: () => {
        ElMessageBox.confirm(
            `检测到新版本，请刷新页面后使用。`,
            '版本更新',
            {
                confirmButtonText: '刷新',
                type: 'warning',
                showClose: false,
                closeOnClickModal: false,
                closeOnPressEscape: false,
                showCancelButton:false
            }
        ).then(() => {
            window.location.reload()
        })
    }
})

app.mount('#app')

VersionChecker 插件接受一个配置对象，支持以下选项：

/**
 * 插件选项接口
 */
export interface VersionCheckerOptions {
    /**
     * 版本信息文件的 URL，指向打包后生成的 version.json
     * 默认值：'/devecoui/version.json'
     * 建议与 Vite 插件生成的文件路径保持一致
     */
    url?: string

    /**
     * 轮询检查版本的间隔时间（毫秒）
     * 默认 2000ms，即每 2 秒检测一次
     * 可以根据项目需求调整，比如大型网站可调长一点
     */
    interval?: number

    /**
     * 当检测到新版本时触发的回调函数
     * 优先于默认弹框行为
     * 可在此回调中自定义刷新逻辑或提示 UI
     */
    onUpdate?: () => void

    /**
     * 自定义弹框函数
     * 若提供，将替代默认 confirm 弹框提示
     * 可用于渲染自定义提示弹窗或 UI 组件
     */
    customPrompt?: () => void,

    /**
     * 是否开启检测
     * 默认开启 true
     * 如果在开发环境下不想检测可以 使用 import.meta.env.PROD 设置为只线上环境检测
     */
    enableDetection?: boolean
}

手动控制

除了作为 Vue 插件使用外，我们还可以在组件中通过引入 startVersionCheck stopVersionCheck checkVersionOnce 方法来手动控制版本检测的开始和停止。

checkVersionOnce 方法会立即进行一次版本检测，而不会启动轮询。返回一个 Promise，解析为检测结果状态。具体参数如下：

入参：

interface CheckVersionOnceOptions {
    /**
     * 自定义弹框函数
     * 若提供，将替代默认 confirm 弹框提示
     * 可用于渲染自定义提示弹窗或 UI 组件
     */
    customPrompt?: () => void,

    /**
     * 是否在有新版本的情况下显示弹框
     * 默认 true
     */
    showPrompt?: boolean
}

结果:

enum VersionCheckResult {
  FETCH_FAILED = 'fetch_failed',    // 获取版本失败
  UP_TO_DATE = 'up_to_date',        // 当前已是最新版本
  UPDATE_AVAILABLE = 'update_available' // 有新版本可用
}

interface VersionFile {
    version: string;     // 版本号（时间戳）
    buildTime: string;   // 构建时间（ISO 字符串）
}

/** 最终返回结果格式 */
interface CheckVersionOnceResult {
    result: VersionCheckResult;      // 检测结果
    currentVersion?: string;         // 当前版本（格式：version@buildTime）
    newVersion?: string;             // 新版本（仅在有更新时存在）
    versionData?: VersionFile;       // 原始版本数据
}