vue-sw-updater 0.0.3 → 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);
             }
         });
@@ -84,7 +84,8 @@ self.addEventListener('fetch', (event) => {
   if (BLACKLIST.some(path => url.pathname.startsWith(path))) return;
 
   // HTML 页面：网络优先，失败回退到缓存 (Network First)
-  if (event.request.mode === 'navigate' || event.request.headers.get('accept').includes('text/html')) {
+  const accept = event.request.headers.get('accept') || '';
+  if (event.request.mode === 'navigate' || accept.includes('text/html')) {
     event.respondWith(
       fetch(event.request)
         .then(response => {
@@ -103,25 +104,41 @@ self.addEventListener('fetch', (event) => {
     return;
   }
 
-  // 静态资源：缓存优先，同时更新缓存 (Stale While Revalidate)
-  // 或者简单的 Cache First，这里为了稳健使用 Cache First + Network Fallback
+  const destination = event.request.destination;
+  const pathname = url.pathname || '';
+  const isScriptOrStyle =
+    destination === 'script' ||
+    destination === 'style' ||
+    pathname.endsWith('.js') ||
+    pathname.endsWith('.css');
+
+  if (isScriptOrStyle) {
+    event.respondWith(
+      fetch(event.request)
+        .catch(() => caches.match(event.request))
+    );
+    return;
+  }
+
   event.respondWith(
-    caches.match(event.request).then((response) => {
-      if (response) {
-        return response;
-      }
-      return fetch(event.request).then(networkResponse => {
-        // 动态缓存请求成功的资源
-        if (!networkResponse || networkResponse.status !== 200 || networkResponse.type !== 'basic') {
+    caches.match(event.request).then((cachedResponse) => {
+      const fetchAndUpdate = fetch(event.request)
+        .then(networkResponse => {
+          if (networkResponse && networkResponse.status === 200 && networkResponse.type === 'basic') {
+            const responseToCache = networkResponse.clone();
+            caches.open(CACHE_NAME).then(cache => {
+              cache.put(event.request, responseToCache);
+            });
+          }
           return networkResponse;
-        }
-        const responseToCache = networkResponse.clone();
-        caches.open(CACHE_NAME).then(cache => {
-            // 避免缓存过大文件或不必要文件，这里可以加过滤逻辑
-            cache.put(event.request, responseToCache);
         });
-        return networkResponse;
-      });
+
+      if (cachedResponse) {
+        event.waitUntil(fetchAndUpdate.catch(() => {}));
+        return cachedResponse;
+      }
+
+      return fetchAndUpdate;
     })
   );
 });