VersionCheck.js - 让前端版本更新变得简单优雅

VersionCheck.js - 让前端版本更新变得简单优雅

在现代Web应用开发中，如何优雅地处理前端版本更新一直是一个重要但容易被忽视的问题。今天我要向大家推荐一款极简但功能强大的前端版本检测工具 —— VersionCheck.js。

🎯 解决什么问题？

相信很多开发者都遇到过这样的困扰：

• 用户访问网站时加载的是旧版本缓存
• 新功能上线后用户看不到更新内容
• 手动刷新页面影响用户体验
• 缺乏有效的版本检测机制

VersionCheck.js 正是为解决这些问题而生！

✨ 核心特性一览

🔄 智能双模式检测

• ETag模式（默认）：通过HTTP响应头自动检测
• 版本文件模式：通过JSON文件版本字段精确控制

⚡ 自动化轮询

• 默认每10分钟自动检测一次
• 页面隐藏时自动暂停，节省资源
• 支持自定义检测频率

🎨 灵活的交互方式

• 内置原生confirm弹窗
• 支持自定义提示文案
• 可配置更新回调函数

🛡️ 健壮的容错机制

• localStorage自动降级到内存存储
• 完善的错误处理和日志记录
• 多环境兼容（UMD模块规范）

📊 为什么选择VersionCheck.js？

特性	VersionCheck.js	其他方案
配置复杂度	极简配置	需要复杂配置
检测准确性	双模式保障	单一模式
用户体验	无感知检测	影响用户体验
兼容性	多环境支持	环境限制多
维护成本	零依赖	需要持续维护

🌟 项目亮点

• 零学习成本：API设计简洁直观
• 高性能：智能暂停机制节省资源
• 高可靠性：完善的错误处理机制
• 高扩展性：丰富的配置选项
• 开源免费：MIT许可证，可商用

📦 安装方式

1. 通过 <script> 标签引入（浏览器环境）

<!-- 生产环境 -->
<script src="dist/index.js"></script>

<!-- 或使用 CDN -->
<script src="https://cdn.jsdelivr.net/npm/version-check-js@latest/dist/index.js"></script>

2. 通过 NPM 安装（Node.js 环境）

# 安装最新版本
npm install version-check-js

# 或使用 yarn
yarn add version-check-js

然后在代码中导入：

// CommonJS 方式
const VersionCheck = require('version-check-js');

// ES6 模块方式
import VersionCheck from 'version-check-js';

3. 通过 unpkg CDN 引入

<script src="https://unpkg.com/version-check-js@latest/dist/index.js"></script>

---

🚀 快速开始

基础用法

// 实例化 VersionCheck
const versionCheck = new VersionCheck({
  url: '/version.json', // 指定版本文件路径（或默认使用 '/' 进入 ETag 模式）
  interval: 60 * 1000, // 设置检测间隔为 1 分钟
  message: '发现新版本，是否立即刷新？', // 自定义提示文案
});

// 启动自动检测
versionCheck.start();

// 停止自动检测
// versionCheck.stop();

// 销毁实例
// versionCheck.destroy();

// 手动触发一次检测
versionCheck.check().then(hasUpdate => {
  console.log('是否有更新:', hasUpdate);
});

自动构建 v2.0.0+

Vite

// vite.config.js
import { VersionCheckPlugin, VersionCheckRules } from 'version-check-js/plugin';

export default {
  plugins: [
    new VersionCheckPlugin({
      output: 'dist/version.json',
      version: VersionCheckRules.dateTime(),
      format: 'json',
    }).vitePlugin(),
  ],
};

Webpack

// webpack.config.js
const { VersionCheckPlugin, VersionCheckRules } = require('version-check-js/plugin');

module.exports = {
  plugins: [
    new VersionCheckPlugin({
      output: 'dist/version.json',
      version: VersionCheckRules.dateTime(),
      format: 'json',
    }).webpackPlugin(),
  ],
};

Vue CLI

// vue.config.js
const { VersionCheckPlugin, VersionCheckRules } = require('version-check-js/plugin');

module.exports = {
  configureWebpack: (config) => {
    config.plugins.push(
      new VersionCheckPlugin({
        output: 'dist/version.json',
        version: VersionCheckRules.dateTime(),
        format: 'json',
      }).webpackPlugin()
    );
  },
};

---

⚙️ 配置项详解

参数名	类型	默认值	描述
url	string	/	检测地址（默认/：ETag 模式；传文件路径如/version.json：版本文件模式。如vue中放在public目录下，需要传/version.json。也可以传入接口地址，通过get请求或者自定义请求(fetchRequest)获取版本号）
interval	number	10 * 60 * 1000（10 分钟）	轮询检测间隔时间（毫秒），建议不小于 30 秒
message	string	检测到新版本，是否立即刷新？	更新提示文案，仅在未设置 onUpdate 时生效
onUpdate	Function	null	自定义更新回调（优先级高于默认 confirm。传入后message无效。当需要自定义弹框提示或无需弹框提示时需要用的此方法）
onError	Function	(err) => console.error('版本检测失败：', err)	错误回调函数，接收错误对象作为参数
onLog	Function	null	操作日志回调函数，用于记录正常操作信息
storage	Object	null	自定义存储配置（需提供 get、set 方法），默认使用 localStorage
t	string	t	重新加载时的时间戳参数名
versionKey	string	version_check_key	用于在 localStorage 中缓存版本标识的键名
initialCheck	boolean	true	是否在执行start方法时立即执行一次版本比对，而非等待首个轮询间隔(为true时,页面可见性变化显示时会执行一次版本检测)
bindVisibility	boolean	true	是否自动监听页面可见性变化：页面隐藏时暂停轮询，显示时自动恢复，节省性能与网络开销
fetchRequest	Function	null	自定义请求函数，优先级高于内部fetch实现(需要返回Promise对象。返回值为版本号)
fetchOptions	Object	{}	自定义fetch选项，优先级高于默认值（当通过接口请求url时需要传入token时可在此处传入。或者使用其他自定义header时可在此处传入。也可以使用fetchRequest）

配置项最佳实践

const versionCheck = new VersionCheck({
  // 基础配置
  url: '/api/version', // 推荐使用具体的 API 接口
  interval: 5 * 60 * 1000, // 5分钟检测一次（生产环境推荐）

  // 用户体验优化
  message: '发现新版本可用，是否立即更新？',

  // 自定义回调
  onUpdate: () => {
    // 自定义更新逻辑
    console.log('执行更新...');
    // 可以在这里添加动画、提示等
    window.location.reload();
  },

  // 错误处理
  onError: error => {
    // 生产环境可以发送错误日志到监控系统
    console.error('版本检测异常:', error);
  },

  // 操作日志
  onLog: message => {
    // 记录操作日志，便于调试
    console.log('VersionCheck:', message);
  },
});

---

🔧 完整 API 文档

实例方法

start()

启动自动轮询检测。

versionCheck.start(); // 返回 undefined

stop([isInternal])

停止自动轮询检测。

versionCheck.stop(); // 外部调用，会触发 onLog
versionCheck.stop(true); // 内部调用，不会触发 onLog

check()

手动触发一次检测，返回 Promise。

try {
  const hasUpdate = await versionCheck.check();
  if (hasUpdate) {
    console.log('检测到新版本！');
  }
} catch (error) {
  console.error('检测失败:', error);
}

reload()

强制刷新页面，自动处理 URL 参数去重。

versionCheck.reload(); // 会添加时间戳参数避免缓存

destroy()

销毁实例，清理所有资源（定时器、事件监听器、存储引用等）。

versionCheck.destroy(); // 实例销毁后不可再次使用

静态属性

checkMode

获取当前检测模式。

console.log(versionCheck.checkMode); // 'etag' 或 'file'

isRunning

获取当前检测状态。

console.log(versionCheck.isRunning); // boolean

---

📝 使用场景和示例

配合 Axios 拦截器使用

// axios 配置
import axios from 'axios';
import VersionCheck from 'version-check-js';

const versionCheck = new VersionCheck({
  url: '/api/version',
  interval: 300000,
  // fetchOptions: {
  //   headers: {
  //     'Authorization': 'Bearer ' + localStorage.getItem('token'),
  //   },
  // },
  // fetchRequest: async (url, options) => {
  //   const response = await axios(url, options);
  //   return response.version;
  // },
});

// 请求拦截器中进行版本检测
axios.interceptors.request.use(
  async config => {
    if (process.env.NODE_ENV === 'production') {
      try {
        await versionCheck.check().then(flag => {
          console.log(flag);
        });
      } catch (error) {
        console.warn('版本检测失败:', error);
      }
    }
    return config;
  },
  error => {
    return Promise.reject(error);
  },
);

versionCheck.start();

---

🛠️ 高级配置和最佳实践

存储策略配置

// 自定义存储适配器
const customStorage = {
  get: function (key) {
    try {
      return localStorage.getItem(key);
    } catch (e) {
      // 降级到 cookie
      return this._getFromCookie(key);
    }
  },

  set: function (key, value) {
    try {
      localStorage.setItem(key, value);
      return true;
    } catch (e) {
      // 降级到 cookie
      return this._setToCookie(key, value);
    }
  },
  // Cookie 操作方法
  _getFromCookie: function (key) {
    /* ... */
  },
  _setToCookie: function (key, value) {
    /* ... */
  },
};

const versionCheck = new VersionCheck({
  storage: customStorage,
});

错误监控集成

const versionCheck = new VersionCheck({
  onError: error => {
    // 发送到自定义监控接口
    fetch('/api/error-report', {
      method: 'POST',
      body: JSON.stringify({
        error: error.message,
        stack: error.stack,
        timestamp: Date.now(),
      }),
    });
  },

  onLog: message => {
    // 记录操作日志
  },
});

性能优化建议

// 生产环境配置
const prodConfig = {
  url: '/api/version',
  interval: 5 * 60 * 1000, // 5分钟（避免过于频繁）
  onError: error => {
    // 生产环境静默处理，避免影响用户体验
    console.debug('Version check error:', error.message);
  },
};

// 开发环境配置
const devConfig = {
  url: '/api/version',
  interval: 30 * 1000, // 30秒（便于调试）
  onLog: message => {
    // 开发环境详细日志
    console.log('🔧 VersionCheck:', message);
  },
};

const versionCheck = new VersionCheck(process.env.NODE_ENV === 'production' ? prodConfig : devConfig);

---

🔗 相关链接

• GitHub仓库：github.com/ybchen292/v…
• Gitee镜像：gitee.com/ybchen292/v…
• 在线文档：查看完整API文档和使用指南

📄 许可证

MIT License

💬 结语

VersionCheck.js以其极简的配置、强大的功能和优雅的设计，成为了前端版本检测领域的优秀解决方案。无论你是个人开发者还是团队项目，都能从中受益。

立即试试VersionCheck.js，让你的应用版本更新变得更加智能和优雅！

---

如果你觉得这个工具不错，欢迎Star我们的GitHub项目，让更多开发者受益！