vue-sw-updater 0.0.4 → 0.0.5

package/README.md

@@ -1,106 +1,142 @@
-# Vue Service Worker Updater
-
-一个基于 Vue 2 和 Ant Design Vue 的项目更新通知与缓存清理方案。
-
-## 功能特性
-
-*   **自动检测更新**: 基于 Service Worker API，自动感知应用版本更新。
-*   **零侵入集成**: Service Worker 逻辑由本库维护，无需手动编写复杂的 SW 代码。
-*   **多环境隔离**: 支持 `appName` 和 `env` 参数，生成独立的缓存空间，避免多应用或多环境缓存冲突。
-*   **全局提示**: 使用 Ant Design Vue Modal 全局弹窗提示用户，样式醒目（警告图标+加粗文字）。
-*   **强制刷新**: 用户点击“立即更新”后，自动清理当前应用缓存并重载页面，确保加载最新资源。
-*   **环境检测**: 自动检测浏览器版本，如果不支持 Service Worker 或版本过低，会显示阻断性提示。
-
-## 安装
-
-```bash
-npm install vue-sw-updater --save
-# 确保项目中已安装 ant-design-vue 和 vue
-npm install ant-design-vue vue --save
-```
-
-## 快速使用
-
-### 1. 引入插件
-
-在你的 `main.js` 或入口文件中：
-
-```javascript
-import Vue from 'vue';
-import VueSWUpdater from 'vue-sw-updater';
-import 'ant-design-vue/dist/antd.css'; 
-
-// 从你的配置或环境变量中获取信息
-const version = process.env.VUE_APP_VERSION || '1.0.0';
-const appName = process.env.VUE_APP_NAME || 'my-app';
-const env = process.env.NODE_ENV || 'production';
-
-Vue.use(VueSWUpdater, {
-  // 必须：应用版本号
-  version: version,
-  
-  // 必须：应用名称（用于隔离缓存）
-  appName: appName,
-  
-  // 必须：部署环境（用于隔离缓存，如 production, staging）
-  env: env,
-  
-  // 可选：Service Worker 文件路径，默认为 /service-worker.js
-  swUrl: '/service-worker.js', 
-  
-  // 可选：调试模式
-  debug: false
-});
-```
-
-### 2. 部署 Service Worker 文件
-
-本库提供了一个通用的 `service-worker.js`，你需要将其包含在你的项目根目录（`public` 目录）中。
-
-**方式 A：构建时复制 (推荐)**
-
-如果你使用 Webpack (Vue CLI)，可以使用 `copy-webpack-plugin` 将本库的 SW 文件复制到你的构建目录。
-
-```javascript
-// vue.config.js
-const CopyWebpackPlugin = require('copy-webpack-plugin');
-const path = require('path');
-
-module.exports = {
-  configureWebpack: {
-    plugins: [
-      new CopyWebpackPlugin({
-        patterns: [
-          {
-            from: path.resolve(__dirname, 'node_modules/vue-sw-updater/dist/service-worker.js'),
-            to: 'service-worker.js' // 输出到 dist 根目录
-          }
-        ]
-      })
-    ]
-  }
-}
-```
-
-## 更新机制说明
-
-1.  当传入的 `version` 发生变化时，插件会注册带有新参数的 Service Worker（例如 `/service-worker.js?v=1.0.1&app=my-app&env=production`）。
-2.  浏览器检测到 URL 变化，重新下载并安装 Service Worker。
-3.  新 SW 初始化时，会根据 `appName` + `env` + `version` 生成全新的 Cache Key。
-4.  当检测到新版本等待激活（Waiting）时，弹出**警告样式**的更新提示框。
-5.  用户点击“立即更新”：
-    *   发送 `SKIP_WAITING` 消息给 SW。
-    *   SW 收到消息后，**立即清理当前应用环境下的旧缓存**。
-    *   SW 执行 `self.skipWaiting()` 激活新版本。
-    *   页面监听到 `controllerchange` 事件，执行 `window.location.reload()` 刷新页面。
-
-## 浏览器支持
-
-插件会自动检测以下浏览器版本要求：
-
-*   Chrome: 45+
-*   Firefox: 44+
-*   Safari: 11+
-*   Edge: 17+
-
-如果用户浏览器版本低于上述要求，将自动显示全屏提示，建议用户升级。
+# Vue Service Worker Updater
+
+一个基于 Vue 2 和 Ant Design Vue 的项目更新通知与缓存清理方案。支持 Service Worker 自动更新和 HTTP 轮询检测更新双重机制，确保在 HTTPS 和 HTTP 环境下均能可靠运行。
+
+## 功能特性
+
+*   **双模更新检测**:
+    *   **Service Worker 模式**: 在 HTTPS 环境下，利用 SW 自动感知应用更新，支持离线缓存和增量更新。
+    *   **HTTP 轮询模式**: 在 HTTP 环境或不支持 SW 的浏览器中，自动降级为 ETag / Last-Modified 轮询检测。
+*   **零侵入集成**: 核心逻辑封装在库内，无需手动编写复杂的 SW 或轮询代码。
+*   **多环境隔离**: 支持 `appName` 和 `env` 参数，生成独立的缓存空间，避免多应用或多环境缓存冲突。
+*   **全局提示**: 使用 Ant Design Vue Modal 全局弹窗提示用户，样式醒目（警告图标+加粗文字）。
+*   **强制刷新**: 用户点击“立即更新”后，自动清理当前应用缓存并重载页面，确保加载最新资源。
+*   **环境自适应**: 自动检测环境安全性（HTTPS/localhost），如果环境不安全且配置了轮询参数，自动切换至轮询模式；否则显示环境不支持提示。
+
+## 安装
+
+```bash
+npm install vue-sw-updater --save
+# 确保项目中已安装 ant-design-vue 和 vue
+npm install ant-design-vue vue --save
+```
+
+## 快速使用
+
+### 1. 引入插件
+
+在你的 `main.js` 或入口文件中：
+
+```javascript
+import Vue from 'vue';
+import VueSWUpdater from 'vue-sw-updater';
+import 'ant-design-vue/dist/antd.css'; 
+
+// 从你的配置或环境变量中获取信息
+const version = process.env.VUE_APP_VERSION || '1.0.0';
+const appName = process.env.VUE_APP_NAME || 'my-app';
+const env = process.env.NODE_ENV || 'production';
+
+Vue.use(VueSWUpdater, {
+  // [必填] 应用版本号 (当前运行的版本)
+  version: version,
+  
+  // [必填] 应用名称（用于 SW 缓存隔离）
+  appName: appName,
+  
+  // [必填] 部署环境（用于 SW 缓存隔离）
+  env: env,
+  
+  // [可选] Service Worker 文件路径，默认为 /service-worker.js
+  swUrl: '/service-worker.js',
+  
+  // [可选] 轮询检测间隔（分钟）。
+  // 如果设置为 > 0，当 SW 不可用（如 HTTP 环境）时，将启用轮询模式。
+  // 建议设置为 10 或 30。
+  pollingInterval: 10,
+
+  // [可选] 检测更新的目标 URL (仅轮询模式使用)
+  // 默认为空字符串 ''，即检测当前页面 (index.html) 的 Header 变化
+  checkUrl: '', 
+  
+  // [可选] 调试模式，开启后控制台会输出更多日志
+  debug: false
+});
+```
+
+### 2. 构建配置 (针对不同模式)
+
+#### A. 准备 Service Worker (HTTPS 模式推荐)
+
+本库提供了一个通用的 `service-worker.js`，你需要将其包含在你的项目根目录（`public` 目录）中。
+
+**Webpack / Vue CLI 配置:**
+
+```javascript
+// vue.config.js
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+const path = require('path');
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      new CopyWebpackPlugin({
+        patterns: [
+          {
+            from: path.resolve(__dirname, 'node_modules/vue-sw-updater/dist/service-worker.js'),
+            to: 'service-worker.js' // 输出到 dist 根目录
+          }
+        ]
+      })
+    ]
+  }
+}
+```
+
+#### B. HTTP 轮询模式配置
+
+无需额外文件。插件会自动轮询当前页面（或指定的 `checkUrl`）的 HTTP 响应头：
+*   **ETag**: 资源唯一标识
+*   **Last-Modified**: 资源最后修改时间
+
+**注意**: 请确保你的 Web 服务器（Nginx/Apache/IIS）已配置为返回这些 Header。对于 SPA 应用的入口文件 (`index.html`)，通常默认都会返回。
+
+## 运行机制
+
+### 自动模式选择
+
+插件初始化时会执行以下判断：
+
+1.  **检查 Service Worker 支持**:
+    *   如果是 HTTPS 或 localhost，且浏览器支持 SW -> **启用 SW 模式**。
+    *   如果是 HTTP (非 localhost) 或浏览器不支持 SW -> **进入降级判断**。
+
+2.  **降级判断**:
+    *   如果配置了 `pollingInterval > 0` -> **启用 HTTP 轮询模式**。
+    *   如果没有配置轮询 -> **显示“环境不支持”错误提示** (BrowserError Modal)。
+
+### SW 模式工作流
+
+1.  插件注册 `service-worker.js?v=1.0.0&app=my-app...`。
+2.  浏览器发现 URL 变化，下载新 SW。
+3.  新 SW 安装并等待激活。
+4.  插件检测到 `waiting` 状态，弹出更新提示框。
+5.  用户点击更新 -> 清理缓存 -> 强制刷新。
+
+### HTTP 轮询模式工作流
+
+1.  插件启动定时器 (例如每 10 分钟)。
+2.  定时发送 `HEAD` 请求检测目标 URL (默认当前页面)。
+3.  对比响应头中的 `ETag` 或 `Last-Modified` 与页面加载时是否一致。
+4.  如果发现 Header 变更，视为有新版本发布，弹出更新提示框。
+5.  用户点击更新 -> 强制刷新 (`window.location.reload(true)`).
+
+## 浏览器支持
+
+插件会自动处理兼容性，最低要求：
+*   **Edge**: 17+
+*   **Chrome**: 45+
+*   **Firefox**: 44+
+*   **Safari**: 11.1+
+
+如果浏览器版本过低，无论哪种模式都会显示阻断性提示。

package/dist/service-worker.js

@@ -22,7 +22,7 @@ const BLACKLIST = [
 console.log(`[VueSWUpdater] Service Worker 初始化. App: ${APP_NAME}, Env: ${ENV}, Version: ${VERSION}, Cache: ${CACHE_NAME}`);
 
 self.addEventListener('install', (event) => {
-  console.log('[VueSWUpdater] Installing...');
+  console.log('[VueSWUpdater] 正在安装...');
   event.waitUntil(
     caches.open(CACHE_NAME).then((cache) => {
       // 仅缓存核心入口文件，其他资源依赖运行时缓存
@@ -30,7 +30,7 @@ self.addEventListener('install', (event) => {
         './',
         './index.html'
       ]).catch(err => {
-        console.warn('[VueSWUpdater] Pre-caching failed:', err);
+        console.warn('[VueSWUpdater] 预缓存失败:', err);
       });
     })
   );
@@ -38,14 +38,14 @@ self.addEventListener('install', (event) => {
 });
 
 self.addEventListener('activate', (event) => {
-  console.log('[VueSWUpdater] Activating...');
+  console.log('[VueSWUpdater] 正在激活...');
   event.waitUntil(
     caches.keys().then((keyList) => {
       return Promise.all(keyList.map((key) => {
         // 清理旧版本缓存 (只清理本插件前缀的缓存)
         // 逻辑：如果是同一个 App 和 Env，但是版本不同，则清理
         if (key.startsWith(CACHE_PREFIX) && key !== CACHE_NAME) {
-          console.log('[VueSWUpdater] Removing old cache:', key);
+          console.log('[VueSWUpdater] 移除旧缓存:', key);
           return caches.delete(key);
         }
       }));
@@ -57,7 +57,7 @@ self.addEventListener('activate', (event) => {
 // 监听 skipWaiting 消息（由 UI 组件触发）
 self.addEventListener('message', (event) => {
   if (event.data && event.data.type === 'SKIP_WAITING') {
-    console.log('[VueSWUpdater] Skip Waiting received');
+    console.log('[VueSWUpdater] 收到 Skip Waiting 指令');
     
     // 强制清理所有缓存（不仅仅是旧版本，确保彻底）
     // 注意：这里只清理当前 APP_NAME 和 ENV 下的缓存，防止误删其他应用缓存
@@ -65,7 +65,7 @@ self.addEventListener('message', (event) => {
     caches.keys().then(keys => {
         keys.forEach(key => {
             if (key.startsWith(CACHE_PREFIX)) {
-                console.log('[VueSWUpdater] Force clearing cache before update:', key);
+                console.log('[VueSWUpdater] 更新前强制清理缓存:', key);
                 caches.delete(key);
             }
         });

package/dist/vue-sw-updater.umd.js

@@ -9842,6 +9842,7 @@ __webpack_require__.r(__webpack_exports__);
 // EXPORTS
 __webpack_require__.d(__webpack_exports__, {
   BrowserError: function() { return /* reexport */ BrowserError; },
+  PollingUpdater: function() { return /* reexport */ PollingUpdater; },
   ServiceWorkerUpdater: function() { return /* reexport */ ServiceWorkerUpdater; },
   UpdateModal: function() { return /* reexport */ UpdateModal; },
   checkBrowserSupport: function() { return /* reexport */ checkBrowserSupport; },
@@ -10038,7 +10039,7 @@ class ServiceWorkerUpdater {
       updated: registration => {
         console.log('新内容可用，请刷新。');
         this.registration = registration;
-        // Trigger the update callback (Show UI)
+        // 触发更新回调 (显示 UI)
         this.onUpdateFound(this);
       },
       offline: () => {
@@ -10050,7 +10051,7 @@ class ServiceWorkerUpdater {
       }
     });
 
-    // Handle controller change (reload page)
+    // 处理 controller 变更 (刷新页面)
     let refreshing = false;
     if (navigator.serviceWorker) {
       navigator.serviceWorker.addEventListener('controllerchange', () => {
@@ -10066,7 +10067,7 @@ class ServiceWorkerUpdater {
     }
   }
 
-  // Called when user accepts the update
+  // 当用户接受更新时调用
   applyUpdate() {
     if (!this.registration || !this.registration.waiting) {
       console.warn('未找到等待中的 Service Worker。');
@@ -10074,7 +10075,7 @@ class ServiceWorkerUpdater {
       window.location.reload();
       return;
     }
-    // Send message to SW to skip waiting
+    // 发送消息给 SW 以跳过等待
     // 这会触发 SW 中的 message 监听，执行 self.skipWaiting()
     // 进而触发 controllerchange，最终执行上面的 window.location.reload()
     this.registration.waiting.postMessage({
@@ -10082,6 +10083,90 @@ class ServiceWorkerUpdater {
     });
   }
 }
+;// ./src/lib/utils/PollingUpdater.js
+class PollingUpdater {
+  constructor(options = {}) {
+    this.checkUrl = options.checkUrl || ''; // 默认为当前页面
+    this.intervalMinutes = options.interval || 0; // 0 表示禁用
+    this.onUpdateFound = options.onUpdateFound || (() => {});
+    this.onError = options.onError || (() => {});
+    this.timer = null;
+
+    // 记录 ETag/Last-Modified 状态
+    this.lastEtag = null;
+    this.lastModified = null;
+  }
+  init() {
+    if (this.intervalMinutes <= 0) {
+      console.log('[VueSWUpdater] 轮询时间未设置或为0，不启用轮询。');
+      return;
+    }
+    console.log(`[VueSWUpdater] 启用 HTTP ETag/Last-Modified 检测，轮询间隔: ${this.intervalMinutes} 分钟`);
+
+    // 执行初始检测以建立基准
+    this.checkUpdate(true);
+    this.startPolling();
+  }
+  startPolling() {
+    const ms = this.intervalMinutes * 60 * 1000;
+    this.timer = setInterval(() => {
+      this.checkUpdate(false);
+    }, ms);
+  }
+  checkUpdate(isInit = false) {
+    // 添加时间戳防止缓存
+    // 处理 checkUrl 已包含查询参数的情况
+    const separator = this.checkUrl.includes('?') ? '&' : '?';
+    // 使用 'check_t' 避免与可能存在的 't' 参数冲突
+    const url = `${this.checkUrl}${separator}check_t=${Date.now()}`;
+    fetch(url, {
+      method: 'HEAD',
+      cache: 'no-cache'
+    }).then(response => {
+      if (!response.ok) {
+        // 如果网络错误或 404，跳过此次检测
+        return;
+      }
+      const etag = response.headers.get('ETag');
+      const lastModified = response.headers.get('Last-Modified');
+      if (isInit) {
+        this.lastEtag = etag;
+        this.lastModified = lastModified;
+        // console.log(`[VueSWUpdater] 初始版本信息 - ETag: ${etag}, Last-Modified: ${lastModified}`);
+      } else {
+        let changed = false;
+
+        // 检查 ETag
+        if (etag && this.lastEtag && etag !== this.lastEtag) {
+          changed = true;
+          console.log(`[VueSWUpdater] 检测到更新 (ETag变化): ${this.lastEtag} -> ${etag}`);
+        }
+        // 检查 Last-Modified (作为后备或补充)
+        else if (lastModified && this.lastModified && lastModified !== this.lastModified) {
+          changed = true;
+          console.log(`[VueSWUpdater] 检测到更新 (Last-Modified变化): ${this.lastModified} -> ${lastModified}`);
+        }
+        if (changed) {
+          this.stopPolling(); // 一旦发现更新，停止轮询
+          this.onUpdateFound(this);
+        }
+      }
+    }).catch(err => {
+      console.error('[VueSWUpdater] 版本检测失败:', err);
+    });
+  }
+  stopPolling() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  applyUpdate() {
+    console.log('[VueSWUpdater] 正在刷新页面以应用更新...');
+    // 强制从服务器重新加载以获取新的 index.html 和资源
+    window.location.reload(true);
+  }
+}
 // EXTERNAL MODULE: ./node_modules/ua-parser-js/src/ua-parser.js
 var ua_parser = __webpack_require__(5135);
 var ua_parser_default = /*#__PURE__*/__webpack_require__.n(ua_parser);
@@ -10089,7 +10174,7 @@ var ua_parser_default = /*#__PURE__*/__webpack_require__.n(ua_parser);
 
 const MIN_VERSIONS = {
   Chrome: 45,
-  // Service Worker supported since 40, but safer to say 45+
+  // Service Worker 自 40 起支持，但建议 45+
   Firefox: 44,
   Safari: 11,
   // Safari 11.1+
@@ -10108,22 +10193,29 @@ function checkBrowserSupport() {
     browserVersion: browser.version
   };
 
-  // 1. Check Service Worker API
+  // 1. 检查 Service Worker API
   if (!('serviceWorker' in navigator)) {
     result.supported = false;
-    result.message = '当前浏览器不支持 Service Worker API。';
+    // 检查是否由于不安全上下文导致
+    const isLocalhost = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1';
+    const isHttps = window.location.protocol === 'https:';
+    if (!isLocalhost && !isHttps) {
+      result.message = 'Service Worker 需要 HTTPS 环境或 localhost。请检查您的访问地址是否安全。';
+    } else {
+      result.message = '当前浏览器不支持 Service Worker API。请尝试升级浏览器或检查浏览器设置。';
+    }
     return result;
   }
 
-  // 2. Check Version
+  // 2. 检查版本
   if (MIN_VERSIONS[name]) {
     if (version < MIN_VERSIONS[name]) {
       result.supported = false;
       result.message = `浏览器版本过低。${name} ${version} < 需要 ${MIN_VERSIONS[name]}+`;
     }
   } else {
-    // Unknown browser, but supports SW (passed step 1)
-    // We can assume it's okay or warn user. Let's assume okay if SW API exists.
+    // 未知浏览器，但支持 SW (通过了步骤 1)
+    // 我们假设它是可用的。如果存在 SW API，则通过。
     console.warn('检测到未知浏览器，但存在 Service Worker API。');
   }
   return result;
@@ -15479,55 +15571,86 @@ var BrowserError_component = normalizeComponent(
 
 
 
+
 // 导出单独的组件和工具，以便高级用户按需使用
 
 const Plugin = {
   install(Vue, options = {}) {
-    // 1. Browser Check
+    // 1. 浏览器环境检测
     const checkResult = checkBrowserSupport();
+    let usePolling = false;
+
+    // 检查是否需要降级到轮询模式
+    // 降级条件：不支持 SW 且设置了轮询间隔
     if (!checkResult.supported) {
-      // Mount BrowserError
-      const ErrorConstructor = Vue.extend(BrowserError);
-      const errorInstance = new ErrorConstructor();
-      errorInstance.$mount();
-      document.body.appendChild(errorInstance.$el);
-
-      // Delay show slightly to ensure mount
-      Vue.nextTick(() => {
-        errorInstance.show(checkResult);
-      });
-      return; // Stop initialization of SW
+      if (options.pollingInterval && options.pollingInterval > 0) {
+        usePolling = true;
+        // 如果通过轮询处理，则不在控制台显示错误信息
+        console.warn('[VueSWUpdater] Service Worker 不可用 (' + checkResult.message + ')，切换到 HTTP 轮询模式。');
+      } else {
+        // 挂载 BrowserError 组件
+        const ErrorConstructor = Vue.extend(BrowserError);
+        const errorInstance = new ErrorConstructor();
+        errorInstance.$mount();
+        document.body.appendChild(errorInstance.$el);
+
+        // 稍作延迟以确保挂载完成
+        Vue.nextTick(() => {
+          errorInstance.show(checkResult);
+        });
+        return; // 停止初始化
+      }
     }
 
-    // 2. Prepare UpdateModal Instance
+    // 2. 准备更新弹窗实例
     let modalInstance = null;
-
-    // 3. Service Worker Updater
-    // 构造带参数的 SW URL
-    let swUrl = options.swUrl || '/service-worker.js';
-    const params = new URLSearchParams();
-    if (options.version) params.append('v', options.version);
-    if (options.appName) params.append('app', options.appName);
-    if (options.env) params.append('env', options.env);
-    const queryString = params.toString();
-    if (queryString) {
-      swUrl += (swUrl.indexOf('?') === -1 ? '?' : '&') + queryString;
-    }
-    const updater = new ServiceWorkerUpdater({
-      swUrl: swUrl,
-      onUpdateFound: () => {
-        if (modalInstance) {
-          modalInstance.show();
+    let updater = null;
+
+    // 3. 初始化更新器
+    if (usePolling) {
+      updater = new PollingUpdater({
+        version: options.version,
+        checkUrl: options.checkUrl,
+        interval: options.pollingInterval,
+        onUpdateFound: () => {
+          if (modalInstance) {
+            modalInstance.show();
+          }
+        },
+        onError: err => {
+          if (options.debug) {
+            console.error('[VueSWUpdater] 轮询错误：', err);
+          }
         }
-      },
-      onError: err => {
-        if (options.debug) {
-          console.error('[VueSWUpdater] SW 注册错误：', err);
+      });
+    } else {
+      // Service Worker Updater
+      // 构造带参数的 SW URL
+      let swUrl = options.swUrl || '/service-worker.js';
+      const params = new URLSearchParams();
+      if (options.version) params.append('v', options.version);
+      if (options.appName) params.append('app', options.appName);
+      if (options.env) params.append('env', options.env);
+      const queryString = params.toString();
+      if (queryString) {
+        swUrl += (swUrl.indexOf('?') === -1 ? '?' : '&') + queryString;
+      }
+      updater = new ServiceWorkerUpdater({
+        swUrl: swUrl,
+        onUpdateFound: () => {
+          if (modalInstance) {
+            modalInstance.show();
+          }
+        },
+        onError: err => {
+          if (options.debug) {
+            console.error('[VueSWUpdater] SW 注册错误：', err);
+          }
         }
-      }
-    });
+      });
+    }
 
-    // 4. Mount UpdateModal
+    // 4. 挂载更新弹窗组件
     const ModalConstructor = Vue.extend(UpdateModal);
     modalInstance = new ModalConstructor({
       propsData: {
@@ -15537,13 +15660,13 @@ const Plugin = {
     modalInstance.$mount();
     document.body.appendChild(modalInstance.$el);
 
-    // 5. Init Updater
-    // Wait for window load to avoid affecting page load performance
+    // 5. 启动更新器
+    // 等待页面加载完成，避免影响首屏性能
     window.addEventListener('load', () => {
       updater.init();
     });
 
-    // 6. Expose to Vue prototype
+    // 6. 挂载到 Vue 原型
     Vue.prototype.$swUpdater = updater;
   }
 };