update-notify-js

📦 项目简介

一个轻量级的纯前端实现的版本更新自动检测和提示刷新插件。它能够自动监测应用的新版本发布，并通过友好的方式通知用户进行更新，确保用户始终使用最新版本的应用。

✨ 核心特性

🎯 自动检测更新：定期轮询检测应用是否有新版本发布
🔄 手动/自动模式：支持自动轮询和手动触发两种工作模式
🎨 多种通知方式：支持系统原生confirm对话框或自定义通知UI
📱 页面可见性感知：可配置在页面隐藏时暂停检测，节省资源
⚡ 轻量高效：核心代码简洁，无第三方依赖
🔧 高度可配置：提供丰富的配置选项以满足不同需求
🌐 多框架支持：支持原生JavaScript、React、Vue等多种框架

📥 安装

# 使用 npm
npm install update-notify-js

# 使用 yarn
yarn add update-notify-js

# 使用 pnpm
pnpm add update-notify-js

🚀 快速开始

1) 原生 HTML + JS（UMD）

自动轮询模式

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>版本更新检测示例</title>
</head>
<body>
  <script src="https://unpkg.com/update-notify-js/dist/index.umd.js"></script>
  <script>
    // 默认自动轮询：每分钟检测一次，并打印日志与回调
    WebVersionChecker.createUpdateNotifier({
      pollingInterval: 60000,
      debug: true,
      onDetected: () => {
        console.log('[update-notify-js] 检测到新版本');
      },
      // 使用自定义提示：确认后手动刷新（演示 location.reload）
      notifyType: 'custom',
      onUpdate: () => {
        console.log('[update-notify-js] 准备刷新页面以更新版本');
        const ok = confirm('检测到新版本，是否立即刷新页面以更新？');
        if (ok) {
          // 手动刷新页面
          location.reload();
          // 返回 false，避免插件再次调用刷新（因为我们已手动刷新）
          return false;
        }
        return false;
      }
    });
  </script>
</body>
</html>

手动启动暂停模式

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>版本更新检测示例</title>
</head>
<body>
  <script src="https://unpkg.com/update-notify-js/dist/index.umd.js"></script>
  <script>
    // 手动模式：禁用自动轮询，自己控制检测时机
    const notifier = WebVersionChecker.createUpdateNotifier({
      pollingInterval: null, // 禁用自动轮询
      debug: true,
      onDetected: () => {
        console.log('[update-notify-js] 检测到新版本');
      }
    });
    
    // 手动启动检测（例如点击按钮时）
    document.getElementById('checkUpdateBtn').addEventListener('click', async () => {
      const hasUpdate = await notifier.checkUpdate();
      console.log('检测完成，是否有更新:', hasUpdate);
    });
    
    // 也可以使用 checkNow 静默检测
    document.getElementById('checkSilentBtn').addEventListener('click', async () => {
      const hasUpdate = await notifier.checkNow();
      console.log('静默检测完成，是否有更新:', hasUpdate);
      if (hasUpdate) {
        // 自定义提示逻辑
        if (confirm('发现新版本，是否刷新页面？')) {
          location.reload();
        }
      }
    });
  </script>
  
  <button id="checkUpdateBtn">检查更新并提示</button>
  <button id="checkSilentBtn">静默检查更新</button>
</body>
</html>

2) Vue + TypeScript（main.ts）

自动轮询模式

import { createApp } from 'vue';
import App from './App.vue';
import { createUpdateNotifier, type UpdateNotifierOptions } from 'update-notify-js';

createApp(App).mount('#app');

// 仅生产环境启用
if (import.meta.env.PROD) {
  const options: UpdateNotifierOptions = {
    pollingInterval: 60000,
    notifyType: 'confirm',
    promptMessage: '发现新版本，是否立即刷新？',
    onDetected: () => {
      console.log('检测到新版本');
    }
  };
  createUpdateNotifier(options);
}

手动启动暂停模式

import { createApp } from 'vue';
import App from './App.vue';
import { createUpdateNotifier, type UpdateNotifierOptions } from 'update-notify-js';

const app = createApp(App);
app.mount('#app');

// 仅生产环境启用
if (import.meta.env.PROD) {
  // 手动模式：禁用自动轮询
  const options: UpdateNotifierOptions = {
    pollingInterval: null, // 禁用自动轮询
    notifyType: 'confirm',
    promptMessage: '发现新版本，是否立即刷新？',
    onDetected: () => {
      console.log('检测到新版本');
    }
  };
  
  const notifier = createUpdateNotifier(options);
  
  // 在需要时手动检测更新
  window.checkForUpdate = async () => {
    const hasUpdate = await notifier.checkUpdate();
    console.log('检测完成，是否有更新:', hasUpdate);
  };
  
  // 静默检测
  window.checkSilently = async () => {
    const hasUpdate = await notifier.checkNow();
    console.log('静默检测完成，是否有更新:', hasUpdate);
  };
}

3) React + TypeScript（index.tsx）

自动轮询模式

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { createUpdateNotifier, type UpdateNotifierOptions } from 'update-notify-js';

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

if (process.env.NODE_ENV === 'production') {
  const options: UpdateNotifierOptions = {
    pollingInterval: 60000,
    notifyType: 'confirm',
    promptMessage: '发现新版本，是否立即刷新？',
    debug: false
  };
  createUpdateNotifier(options);
}

手动启动暂停模式

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { createUpdateNotifier, type UpdateNotifierOptions } from 'update-notify-js';

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

if (process.env.NODE_ENV === 'production') {
  // 手动模式：禁用自动轮询
  const options: UpdateNotifierOptions = {
    pollingInterval: null, // 禁用自动轮询
    notifyType: 'confirm',
    promptMessage: '发现新版本，是否立即刷新？',
    debug: false
  };
  
  const notifier = createUpdateNotifier(options);
  
  // 暴露到全局供组件调用
  window.versionNotifier = notifier;
}

📚 API 文档

UpdateNotifierOptions 配置选项

配置项	类型	默认值	说明
`pollingInterval`	`number \| null`	`10000`	轮询间隔时间（毫秒）。设置为 `null` 或 `0` 则禁用自动轮询，进入手动模式
`notifyType`	`'confirm' \| 'custom'`	`'confirm'`	提示用户更新的方式。`'confirm'` 使用系统原生对话框，`'custom'` 使用自定义函数
`onUpdate`	`() => boolean \| Promise<boolean>`	`undefined`	自定义更新提示函数（当 `notifyType='custom'` 时使用），返回 `true` 表示确认刷新
`onDetected`	`() => void`	`() => {}`	检测到更新时的回调函数
`pauseOnHidden`	`boolean`	`true`	是否在页面隐藏时暂停检测（仅在自动轮询模式下有效）
`immediate`	`boolean`	`true`	是否立即开始检测（仅在自动轮询模式下有效）
`indexPath`	`string \| string[]`	`'/'`	自定义请求路径，可以是单个路径字符串或路径数组。在微前端场景中，可以配置多个子应用入口路径进行统一检测
`scriptRegex`	`RegExp`	`/<script.*src=["'](?<src>[^"']+)/gm`	script 标签正则匹配，用于自定义匹配规则
`excludeScripts`	`string[] \| RegExp`	`undefined`	需要排除的脚本路径列表，支持字符串数组（支持 * 和 ? 通配符）或正则表达式
`debug`	`boolean`	`false`	是否在控制台输出日志
`promptMessage`	`string`	`'检测到新版本，点击确定将刷新页面并更新'`	默认 confirm 提示文案（用于 `notifyType='confirm'`）
`cacheControl`	`RequestCache`	`'no-cache'`	fetch 请求的缓存控制选项，默认为 'no-cache'，确保获取最新内容

VersionUpdateNotifier 实例方法

方法名	返回值	说明
`start()`	`void`	开始版本更新检测（仅在自动轮询模式下有效）
`stop()`	`void`	停止版本更新检测（仅在自动轮询模式下有效）
`checkNow()`	`Promise<boolean>`	手动触发一次静默检测，返回是否有更新，但不显示提示
`checkUpdate()`	`Promise<boolean>`	手动触发一次检测，如有更新会显示提示，返回是否有更新
`reset()`	`void`	重置状态，清空历史记录

工厂函数

createUpdateNotifier(options?: UpdateNotifierOptions): VersionUpdateNotifier

创建并返回一个新的版本更新通知器实例。

🔍 工作原理

该插件通过以下方式检测版本更新：

脚本资源对比：定期请求应用的入口HTML文件，提取其中的script标签src属性
变化检测：将提取到的资源列表与之前保存的列表进行对比
更新通知：当发现资源列表发生变化时，认为有新版本发布，通知用户

微前端场景支持

在微前端架构中，可以通过配置indexPath数组来同时监控多个子应用的更新情况：

// 监控多个子应用
const options = {
  pollingInterval: 60000,
  indexPath: [
    '/',                // 主应用
    '/sub-app-1/index.html',  // 子应用1
    '/sub-app-2/index.html'   // 子应用2
  ],
  // 其他配置...
};
createUpdateNotifier(options);

提示：对于大多数现代前端应用，构建过程会在文件名中注入哈希值。当代码变更时，生成的文件名也会改变，因此可以通过检测script标签src的变化来判断是否有新版本。

🛠️ 最佳实践

微前端架构最佳实践

合理配置路径：根据子应用的实际部署路径配置indexPath数组
统一管理更新：在主应用中集中管理所有子应用的更新检测，提供一致的用户体验
差异化配置：可以通过多次调用createUpdateNotifier为不同子应用创建不同的检测实例，实现差异化的更新策略
使用手动模式：对于微前端场景，建议使用手动模式并结合用户操作或应用生命周期事件触发检测

// 为不同子应用创建不同的检测实例
const mainAppNotifier = createUpdateNotifier({
  indexPath: '/',
  pollingInterval: null,
  notifyType: 'custom',
  onUpdate: () => {
    // 主应用更新提示，可能需要更谨慎的处理
    return confirm('主应用有更新，确定要刷新吗？这将影响所有正在使用的子应用');
  }
});

const subAppNotifier = createUpdateNotifier({
  indexPath: ['/sub-app-1', '/sub-app-2'],
  pollingInterval: null,
  notifyType: 'custom',
  onUpdate: () => {
    // 子应用更新提示
    return confirm('检测到子应用有更新，确定要刷新页面吗？');
  }
});

// 在合适的时机触发检测
function checkAllUpdates() {
  mainAppNotifier.checkUpdate();
  subAppNotifier.checkUpdate();
}

### 仅在生产环境启用

建议只在生产环境中启用更新检测，以避免开发过程中的干扰：

```ts
// Vue + Vite
if (import.meta.env.PROD) {
  createUpdateNotifier(/* options */);
}

// React + Webpack
if (process.env.NODE_ENV === 'production') {
  createUpdateNotifier(/* options */);
}

合理设置轮询间隔

轮询间隔不宜过短，建议至少30秒以上，以避免过多的网络请求：

const options = {
  pollingInterval: 60000, // 1分钟
  // 其他配置...
};

使用自定义通知UI

对于需要更美观的用户界面，可以使用自定义通知：

const options = {
  notifyType: 'custom',
  onUpdate: async () => {
    // 显示自定义通知UI
    // 例如：使用Toast、Modal等组件
    return await showCustomNotification(); // 返回用户是否确认更新
  }
};

🤝 贡献指南

欢迎通过以下方式参与贡献：

提交Issue报告bug或建议新功能
Fork仓库并提交Pull Request
完善文档和示例

📄 许可证

MIT

🌐 相关链接

感谢使用 update-notify-js！如有任何问题，欢迎在GitHub上提交Issue。

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

update-notify-js

📦 项目简介

✨ 核心特性

📥 安装

🚀 快速开始

1) 原生 HTML + JS（UMD）

自动轮询模式

手动启动暂停模式

2) Vue + TypeScript（main.ts）

自动轮询模式

手动启动暂停模式

3) React + TypeScript（index.tsx）

自动轮询模式

手动启动暂停模式

📚 API 文档

UpdateNotifierOptions 配置选项

VersionUpdateNotifier 实例方法

工厂函数

🔍 工作原理

微前端场景支持

🛠️ 最佳实践

微前端架构最佳实践

合理设置轮询间隔

使用自定义通知UI

🤝 贡献指南

📄 许可证

🌐 相关链接

About

Uh oh!

Releases 1

Packages

Languages

License

wangkai000/update-notify-js

Folders and files

Latest commit

History

Repository files navigation

update-notify-js

📦 项目简介

✨ 核心特性

📥 安装

🚀 快速开始

1) 原生 HTML + JS（UMD）

自动轮询模式

手动启动暂停模式

2) Vue + TypeScript（main.ts）

自动轮询模式

手动启动暂停模式

3) React + TypeScript（index.tsx）

自动轮询模式

手动启动暂停模式

📚 API 文档

UpdateNotifierOptions 配置选项

VersionUpdateNotifier 实例方法

工厂函数

🔍 工作原理

微前端场景支持

🛠️ 最佳实践

微前端架构最佳实践

合理设置轮询间隔

使用自定义通知UI

🤝 贡献指南

📄 许可证

🌐 相关链接

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages