前端应用的离线暂停更新策略：构建稳定可靠的渐进式部署方案

1. 引言：为什么需要离线暂停更新策略？

背景与痛点：现代前端应用频繁更新带来的用户体验挑战
核心问题：用户正在操作时突然刷新/更新的中断体验
策略价值：保障关键操作连续性，提升用户满意度与系统稳定性

2. 离线暂停更新策略的核心概念

离线检测：如何判断应用处于离线或关键操作状态
暂停机制：延迟或阻止更新的触发条件
恢复策略：在合适时机安全应用更新的方法
版本管理：多版本共存与平滑过渡

3. 技术实现方案对比

3.1 Service Worker 方案

离线缓存控制：通过 Service Worker 拦截请求与资源更新
更新检测与延迟 ：skipWaiting() 与 clients.claim() 的时机控制
用户交互感知：监听页面焦点、用户活动状态

3.2 应用状态感知方案

关键操作标记：在 Redux/Vuex/Pinia 中标记"不可中断"状态
路由守卫拦截：在路由跳转前检查更新状态
自定义生命周期钩子：扩展框架生命周期以集成更新控制

3.3 混合方案（推荐）

Service Worker + 状态管理：结合离线能力与业务状态感知
智能决策层：基于操作类型、网络状态、用户偏好的更新决策

4. 详细实现步骤

下图展示了离线暂停更新策略的核心决策流程，帮助理解从用户操作到最终更新决策的完整链路：
#mermaid-svg-YQM6ksIeQtysBWXY{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-YQM6ksIeQtysBWXY .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-YQM6ksIeQtysBWXY .error-icon{fill:#552222;}#mermaid-svg-YQM6ksIeQtysBWXY .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-YQM6ksIeQtysBWXY .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-YQM6ksIeQtysBWXY .marker{fill:#333333;stroke:#333333;}#mermaid-svg-YQM6ksIeQtysBWXY .marker.cross{stroke:#333333;}#mermaid-svg-YQM6ksIeQtysBWXY svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-YQM6ksIeQtysBWXY p{margin:0;}#mermaid-svg-YQM6ksIeQtysBWXY .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-YQM6ksIeQtysBWXY .cluster-label text{fill:#333;}#mermaid-svg-YQM6ksIeQtysBWXY .cluster-label span{color:#333;}#mermaid-svg-YQM6ksIeQtysBWXY .cluster-label span p{background-color:transparent;}#mermaid-svg-YQM6ksIeQtysBWXY .label text,#mermaid-svg-YQM6ksIeQtysBWXY span{fill:#333;color:#333;}#mermaid-svg-YQM6ksIeQtysBWXY .node rect,#mermaid-svg-YQM6ksIeQtysBWXY .node circle,#mermaid-svg-YQM6ksIeQtysBWXY .node ellipse,#mermaid-svg-YQM6ksIeQtysBWXY .node polygon,#mermaid-svg-YQM6ksIeQtysBWXY .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-YQM6ksIeQtysBWXY .rough-node .label text,#mermaid-svg-YQM6ksIeQtysBWXY .node .label text,#mermaid-svg-YQM6ksIeQtysBWXY .image-shape .label,#mermaid-svg-YQM6ksIeQtysBWXY .icon-shape .label{text-anchor:middle;}#mermaid-svg-YQM6ksIeQtysBWXY .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-YQM6ksIeQtysBWXY .rough-node .label,#mermaid-svg-YQM6ksIeQtysBWXY .node .label,#mermaid-svg-YQM6ksIeQtysBWXY .image-shape .label,#mermaid-svg-YQM6ksIeQtysBWXY .icon-shape .label{text-align:center;}#mermaid-svg-YQM6ksIeQtysBWXY .node.clickable{cursor:pointer;}#mermaid-svg-YQM6ksIeQtysBWXY .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-YQM6ksIeQtysBWXY .arrowheadPath{fill:#333333;}#mermaid-svg-YQM6ksIeQtysBWXY .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-YQM6ksIeQtysBWXY .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-YQM6ksIeQtysBWXY .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-YQM6ksIeQtysBWXY .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-YQM6ksIeQtysBWXY .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-YQM6ksIeQtysBWXY .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-YQM6ksIeQtysBWXY .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-YQM6ksIeQtysBWXY .cluster text{fill:#333;}#mermaid-svg-YQM6ksIeQtysBWXY .cluster span{color:#333;}#mermaid-svg-YQM6ksIeQtysBWXY div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-YQM6ksIeQtysBWXY .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-YQM6ksIeQtysBWXY rect.text{fill:none;stroke-width:0;}#mermaid-svg-YQM6ksIeQtysBWXY .icon-shape,#mermaid-svg-YQM6ksIeQtysBWXY .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-YQM6ksIeQtysBWXY .icon-shape p,#mermaid-svg-YQM6ksIeQtysBWXY .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-YQM6ksIeQtysBWXY .icon-shape .label rect,#mermaid-svg-YQM6ksIeQtysBWXY .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-YQM6ksIeQtysBWXY .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-YQM6ksIeQtysBWXY .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-YQM6ksIeQtysBWXY :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 有关键操作进行中
无关键操作
检测到新版本
无新版本
页面在后台

且无关键操作
页面活跃

且无关键操作
有关键操作进行中
用户确认
用户取消
页面在后台
页面活跃
用户操作开始
应用状态检测
标记为关键操作状态
保持正常状态
延迟更新应用
Service Worker 更新检测
决策引擎
继续当前版本
立即应用更新
显示更新通知

等待用户确认
延迟更新

等待操作完成
刷新页面

加载新版本
保持当前版本

下次再提示
操作完成
检查页面状态
流程结束

流程说明：

用户操作开始：用户开始与前端应用交互
应用状态检测：系统检测当前是否有关键操作（如支付、表单提交）进行中
Service Worker 更新检测：后台 Service Worker 检测到新版本可用
决策引擎 ：基于以下因素做出决策：
- 页面是否在后台（document.hidden）
- 是否有关键操作进行中
- 用户是否处于活跃状态
三种决策路径 ：
- 立即应用：页面在后台且无关键操作时自动应用
- 用户确认：页面活跃时提示用户选择时机
- 延迟应用：有关键操作时等待操作完成
最终执行：根据决策刷新页面加载新版本或保持当前版本

这个流程图清晰地展示了混合方案中状态感知与 Service Worker 协同工作的决策逻辑，为后续的具体实现提供了可视化指导。

4.1 环境准备与基础配置

注册 Service Worker 并配置缓存策略
设置应用状态管理器（以 Redux 为例）

4.2 更新检测与状态管理

javascript 复制代码

// 示例：更新检测与状态管理
class UpdateManager {
  constructor() {
    this.isCriticalOperation = false;
    this.pendingUpdate = null;
  }
  
  // 检测到新版本时的处理
  onUpdateFound(registration) {
    // 存储待应用的更新
    this.pendingUpdate = registration.waiting;
    
    // 根据当前状态决定是否立即应用
    if (!this.isCriticalOperation) {
      this.applyUpdate();
    } else {
      this.showUpdateNotification();
    }
  }
}

javascript 复制代码

// Vue 3 Composition API 版本 UpdateManager
import { ref, readonly, computed, onMounted, onUnmounted } from 'vue';
import { useEventListener } from '@vueuse/core'; // 可选，简化事件监听

/**
 * Vue 3 Composition API 实现的离线更新管理器
 * 提供关键操作标记、更新检测和应用逻辑
 */
export function useUpdateManager() {
  // 响应式状态
  const isCriticalOperation = ref(false);
  const pendingUpdate = ref(null);
  const updateAvailable = ref(false);
  const userAcknowledgedUpdate = ref(false);

  // 关键操作标记管理
  const criticalOperations = ref(new Set());

  /**
   * 标记关键操作开始
   * @param {string} operationId - 操作标识符
   */
  const startCriticalOperation = (operationId) => {
    criticalOperations.value.add(operationId);
    isCriticalOperation.value = true;
    console.log(`[UpdateManager] 关键操作开始: ${operationId}`);
  };

  /**
   * 标记关键操作结束
   * @param {string} operationId - 操作标识符
   */
  const endCriticalOperation = (operationId) => {
    criticalOperations.value.delete(operationId);
    isCriticalOperation.value = criticalOperations.value.size > 0;
    console.log(`[UpdateManager] 关键操作结束: ${operationId}`);
    
    // 如果没有关键操作且有待处理的更新，尝试应用
    if (!isCriticalOperation.value && pendingUpdate.value) {
      applyPendingUpdate();
    }
  };

  /**
   * 检查当前是否有任何关键操作进行中
   */
  const hasCriticalOperations = computed(() => isCriticalOperation.value);

  // Service Worker 更新检测
  const checkForUpdates = async () => {
    if (!('serviceWorker' in navigator)) {
      console.warn('[UpdateManager] 当前浏览器不支持 Service Worker');
      return;
    }

    try {
      const registration = await navigator.serviceWorker.getRegistration();
      if (!registration) {
        console.log('[UpdateManager] 未找到 Service Worker 注册');
        return;
      }

      // 监听更新找到事件
      registration.addEventListener('updatefound', () => {
        const newWorker = registration.installing;
        if (!newWorker) return;

        newWorker.addEventListener('statechange', () => {
          if (newWorker.state === 'installed') {
            handleUpdateFound(registration);
          }
        });
      });

      // 检查是否有等待中的更新
      if (registration.waiting) {
        handleUpdateFound(registration);
      }

      // 定期检查更新（每5分钟）
      setInterval(async () => {
        await registration.update();
      }, 5 * 60 * 1000);

    } catch (error) {
      console.error('[UpdateManager] 更新检查失败:', error);
    }
  };

  /**
   * 处理发现更新
   * @param {ServiceWorkerRegistration} registration
   */
  const handleUpdateFound = (registration) => {
    pendingUpdate.value = registration.waiting;
    updateAvailable.value = true;
    
    console.log('[UpdateManager] 检测到新版本可用');

    // 根据当前状态决定处理方式
    if (!isCriticalOperation.value) {
      // 无关键操作，立即应用
      applyUpdate();
    } else {
      // 有关键操作，显示通知
      showUpdateNotification();
    }
  };

  /**
   * 应用待处理的更新
   */
  const applyUpdate = () => {
    if (!pendingUpdate.value) {
      console.warn('[UpdateManager] 没有待处理的更新');
      return;
    }

    console.log('[UpdateManager] 正在应用更新...');
    
    // 发送 skipWaiting 消息给等待中的 Service Worker
    pendingUpdate.value.postMessage({ type: 'SKIP_WAITING' });
    
    // 监听状态变化
    pendingUpdate.value.addEventListener('statechange', (e) => {
      if (e.target.state === 'activated') {
        console.log('[UpdateManager] 更新已激活，即将刷新页面');
        window.location.reload();
      }
    });
  };

  /**
   * 应用待处理的更新（安全版本）
   */
  const applyPendingUpdate = () => {
    if (!pendingUpdate.value || isCriticalOperation.value) {
      return;
    }

    // 检查页面是否在后台或用户是否空闲
    const isPageHidden = document.hidden;
    const isUserActive = Date.now() - lastUserActivity.value < 5 * 60 * 1000; // 5分钟内无活动

    if (isPageHidden || !isUserActive) {
      applyUpdate();
    } else {
      // 页面活跃，询问用户
      showUpdateNotification();
    }
  };

  /**
   * 显示更新通知
   */
  const showUpdateNotification = () => {
    // 在实际应用中，这里可以显示一个 UI 通知组件
    console.log('[UpdateManager] 显示更新通知');
    
    // 示例：使用浏览器的 Notification API
    if ('Notification' in window && Notification.permission === 'granted') {
      new Notification('新版本可用', {
        body: '应用有更新可用，是否立即应用？',
        icon: '/icon.png'
      }).onclick = () => {
        userAcknowledgedUpdate.value = true;
        applyUpdate();
      };
    }
    
    // 或者触发一个自定义事件，让父组件显示通知
    window.dispatchEvent(new CustomEvent('update-available', {
      detail: { applyUpdate }
    }));
  };

  // 用户活动追踪
  const lastUserActivity = ref(Date.now());
  const trackUserActivity = () => {
    lastUserActivity.value = Date.now();
  };

  // 生命周期钩子
  onMounted(() => {
    // 初始化 Service Worker 检查
    checkForUpdates();
    
    // 监听用户活动
    useEventListener(document, 'click', trackUserActivity);
    useEventListener(document, 'keydown', trackUserActivity);
    useEventListener(document, 'mousemove', trackUserActivity);
    
    // 监听页面可见性变化
    useEventListener(document, 'visibilitychange', () => {
      if (document.hidden && pendingUpdate.value && !isCriticalOperation.value) {
        // 页面切到后台且无关键操作，应用更新
        applyUpdate();
      }
    });
    
    // 监听来自 Service Worker 的消息
    navigator.serviceWorker?.addEventListener('message', (event) => {
      if (event.data.type === 'UPDATE_AVAILABLE') {
        handleUpdateFound(event.data.registration);
      }
    });
  });

  onUnmounted(() => {
    // 清理操作
    criticalOperations.value.clear();
  });

  return {
    // 状态（只读）
    isCriticalOperation: readonly(isCriticalOperation),
    updateAvailable: readonly(updateAvailable),
    hasCriticalOperations: readonly(hasCriticalOperations),
    
    // 操作方法
    startCriticalOperation,
    endCriticalOperation,
    applyUpdate,
    applyPendingUpdate,
    showUpdateNotification,
    
    // 工具方法
    checkForUpdates,
  };
}

/**
 * 在 Vue 组件中使用示例
 * 
 * ```vue
 * <template>
 *   <div>
 *     <button @click="startCheckout">开始结账</button>
 *     <button @click="applyUpdate" v-if="updateAvailable">
 *       应用更新
 *     </button>
 *   </div>
 * </template>
 * 
 * <script setup>
 * import { useUpdateManager } from './useUpdateManager';
 * 
 * const {
 *   isCriticalOperation,
 *   updateAvailable,
 *   startCriticalOperation,
 *   endCriticalOperation,
 *   applyUpdate
 * } = useUpdateManager();
 * 
 * const startCheckout = () => {
 *   startCriticalOperation('checkout');
 *   // 结账逻辑...
 *   setTimeout(() => {
 *     endCriticalOperation('checkout');
 *   }, 5000);
 * };
 * </script>
 * ```
 */

4.2.1 Vue 3 Composition API 实现详解

核心特性：

响应式状态管理 ：使用 ref 和 computed 实现响应式状态，自动触发 UI 更新
关键操作追踪：支持多个并发关键操作，使用 Set 数据结构管理
智能更新决策：结合页面可见性、用户活动状态和关键操作状态
生命周期集成：自动在组件挂载时初始化，卸载时清理
TypeScript 友好：完整的类型提示（实际使用时可添加类型定义）

使用方式：

javascript 复制代码

// 在组件中使用
import { useUpdateManager } from '@/composables/useUpdateManager';

const updateManager = useUpdateManager();

// 标记关键操作
updateManager.startCriticalOperation('payment-process');
// ...执行支付逻辑
updateManager.endCriticalOperation('payment-process');

// 手动检查更新
updateManager.checkForUpdates();

// 响应式状态可在模板中使用
// {{ updateManager.updateAvailable ? '有更新可用' : '已是最新' }}

与 Service Worker 的集成：

在 Service Worker 中发送更新通知：

javascript 复制代码

// service-worker.js
self.addEventListener('message', (event) => {
  if (event.data.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

// 当新版本安装完成时
self.addEventListener('install', (event) => {
  // 通知所有客户端
  event.waitUntil(
    self.clients.matchAll().then((clients) => {
      clients.forEach((client) => {
        client.postMessage({
          type: 'UPDATE_AVAILABLE',
          registration: self.registration
        });
      });
    })
  );
});

4.3 关键操作标记与监听

定义"关键操作"类型（如表单提交、支付流程、文件上传）
在操作开始/结束时更新全局状态
监听页面可见性、网络状态变化

4.4 更新应用时机决策

立即应用：页面后台、无关键操作、用户空闲时
延迟应用：有关键操作进行中、页面活跃时
用户确认：提供更新通知，让用户选择时机

4.5 安全恢复与回滚机制

确保更新失败时可回退到稳定版本
数据同步与状态恢复策略
错误边界与降级方案

5. 实战案例：电商购物车场景

5.1 场景分析

用户添加商品到购物车
填写收货地址与支付信息
提交订单过程中的更新风险

5.2 实现方案

javascript 复制代码

// 购物车关键操作标记
const cartCriticalOperations = {
  addToCart: true,
  updateQuantity: true,
  checkout: true, // 结账为最高优先级
  payment: true
};

// 在结账流程中暂停更新
checkoutService.startCheckout(() => {
  updateManager.setCriticalOperation(true);
  // ... 结账逻辑
  updateManager.setCriticalOperation(false);
});

5.3 用户体验优化

非阻塞式更新提示
进度保存与恢复
更新后的数据同步

6. 性能与兼容性考虑

6.1 性能影响

Service Worker 注册与更新的开销
状态监听的内存占用
更新延迟对资源加载的影响

6.2 浏览器兼容性

Service Worker 支持情况
备用方案：AppCache（已废弃）的替代方案
渐进增强策略

6.3 缓存策略优化

静态资源与动态内容的缓存分离
版本号管理与缓存清理
预加载与懒加载的平衡

7. 测试与监控

7.1 测试策略

单元测试：更新管理器的状态逻辑
集成测试：Service Worker 与应用的交互
E2E 测试：真实用户场景下的更新流程

7.2 监控指标

更新成功率与失败率
平均更新延迟时间
用户中断操作的比例变化
关键业务漏斗的转化率影响

前端性能监控代码示例：

以下是一个可复用的前端性能监控模块，用于追踪更新成功率、平均更新延迟时间等关键指标。该模块包含数据收集、本地存储和上报到分析平台的功能。

javascript 复制代码

// update-metrics-monitor.js
/**
 * 更新指标监控器
 * 用于追踪离线暂停更新策略的关键性能指标
 */
class UpdateMetricsMonitor {
  constructor(options = {}) {
    this.options = {
      appId: 'your-app-id',
      endpoint: 'https://analytics.yourdomain.com/api/update-metrics',
      localStorageKey: 'update_metrics',
      maxLocalStorageSize: 100, // 最大本地存储记录数
      autoFlushInterval: 30000, // 30秒自动上报
      ...options
    };

    this.metrics = {
      // 更新成功率相关
      updateAttempts: 0,
      updateSuccesses: 0,
      updateFailures: 0,
      
      // 延迟时间相关
      updateDelays: [],
      totalDelay: 0,
      
      // 用户行为相关
      userInterruptedOperations: 0,
      userConfirmedUpdates: 0,
      userDelayedUpdates: 0,
      
      // 时间戳记录
      lastUpdateCheck: null,
      lastUpdateApplied: null,
      criticalOperationStartTimes: new Map()
    };

    this.init();
  }

  /**
   * 初始化监控器
   */
  init() {
    // 从本地存储恢复历史数据
    this.loadFromLocalStorage();
    
    // 设置自动上报
    if (this.options.autoFlushInterval > 0) {
      setInterval(() => this.flushMetrics(), this.options.autoFlushInterval);
    }

    // 监听页面卸载事件，确保数据不丢失
    window.addEventListener('beforeunload', () => {
      this.saveToLocalStorage();
      this.flushMetrics(true); // 同步上报
    });

    console.log('[UpdateMetricsMonitor] 监控器已初始化');
  }

  /**
   * 记录更新检查开始
   */
  recordUpdateCheck() {
    this.metrics.lastUpdateCheck = Date.now();
    this.saveToLocalStorage();
  }

  /**
   * 记录更新发现
   * @param {Object} details - 更新详情
   */
  recordUpdateFound(details = {}) {
    this.metrics.updateAttempts++;
    
    const event = {
      type: 'UPDATE_FOUND',
      timestamp: Date.now(),
      details: {
        version: details.version,
        isCriticalOperation: details.isCriticalOperation || false,
        pageVisibility: document.hidden ? 'hidden' : 'visible',
        ...details
      }
    };

    this.addToQueue(event);
    this.saveToLocalStorage();
  }

  /**
   * 记录更新应用成功
   * @param {Object} details - 成功详情
   */
  recordUpdateSuccess(details = {}) {
    this.metrics.updateSuccesses++;
    this.metrics.lastUpdateApplied = Date.now();
    
    // 计算延迟时间
    if (this.metrics.lastUpdateCheck) {
      const delay = Date.now() - this.metrics.lastUpdateCheck;
      this.metrics.updateDelays.push(delay);
      this.metrics.totalDelay += delay;
      
      // 保持最近100条记录
      if (this.metrics.updateDelays.length > 100) {
        const removed = this.metrics.updateDelays.shift();
        this.metrics.totalDelay -= removed;
      }
    }

    const event = {
      type: 'UPDATE_SUCCESS',
      timestamp: Date.now(),
      details: {
        delay: this.metrics.lastUpdateCheck ? Date.now() - this.metrics.lastUpdateCheck : null,
        strategy: details.strategy || 'auto',
        ...details
      }
    };

    this.addToQueue(event);
    this.saveToLocalStorage();
  }

  /**
   * 记录更新应用失败
   * @param {Object} error - 错误信息
   */
  recordUpdateFailure(error) {
    this.metrics.updateFailures++;
    
    const event = {
      type: 'UPDATE_FAILURE',
      timestamp: Date.now(),
      error: {
        message: error.message,
        code: error.code,
        stack: error.stack
      }
    };

    this.addToQueue(event);
    this.saveToLocalStorage();
  }

  /**
   * 记录关键操作开始
   * @param {string} operationId - 操作标识符
   */
  recordCriticalOperationStart(operationId) {
    this.metrics.criticalOperationStartTimes.set(operationId, Date.now());
    
    const event = {
      type: 'CRITICAL_OPERATION_START',
      timestamp: Date.now(),
      operationId,
      details: {
        pageVisibility: document.hidden ? 'hidden' : 'visible'
      }
    };

    this.addToQueue(event);
  }

  /**
   * 记录关键操作结束
   * @param {string} operationId - 操作标识符
   * @param {boolean} wasInterrupted - 是否被更新中断
   */
  recordCriticalOperationEnd(operationId, wasInterrupted = false) {
    const startTime = this.metrics.criticalOperationStartTimes.get(operationId);
    const duration = startTime ? Date.now() - startTime : null;
    
    this.metrics.criticalOperationStartTimes.delete(operationId);
    
    if (wasInterrupted) {
      this.metrics.userInterruptedOperations++;
    }

    const event = {
      type: 'CRITICAL_OPERATION_END',
      timestamp: Date.now(),
      operationId,
      details: {
        duration,
        wasInterrupted,
        pageVisibility: document.hidden ? 'hidden' : 'visible'
      }
    };

    this.addToQueue(event);
    this.saveToLocalStorage();
  }

  /**
   * 记录用户确认更新
   */
  recordUserConfirmedUpdate() {
    this.metrics.userConfirmedUpdates++;
    
    const event = {
      type: 'USER_CONFIRMED_UPDATE',
      timestamp: Date.now()
    };

    this.addToQueue(event);
    this.saveToLocalStorage();
  }

  /**
   * 记录用户延迟更新
   */
  recordUserDelayedUpdate() {
    this.metrics.userDelayedUpdates++;
    
    const event = {
      type: 'USER_DELAYED_UPDATE',
      timestamp: Date.now()
    };

    this.addToQueue(event);
    this.saveToLocalStorage();
  }

  /**
   * 获取关键指标
   */
  getMetrics() {
    const successRate = this.metrics.updateAttempts > 0 
      ? (this.metrics.updateSuccesses / this.metrics.updateAttempts * 100).toFixed(2)
      : 0;
    
    const avgDelay = this.metrics.updateDelays.length > 0
      ? Math.round(this.metrics.totalDelay / this.metrics.updateDelays.length)
      : 0;
    
    const interruptionRate = (this.metrics.updateSuccesses + this.metrics.updateFailures) > 0
      ? (this.metrics.userInterruptedOperations / (this.metrics.updateSuccesses + this.metrics.updateFailures) * 100).toFixed(2)
      : 0;

    return {
      // 基础统计
      updateAttempts: this.metrics.updateAttempts,
      updateSuccesses: this.metrics.updateSuccesses,
      updateFailures: this.metrics.updateFailures,
      successRate: `${successRate}%`,
      
      // 延迟统计
      avgUpdateDelay: `${avgDelay}ms`,
      recentDelays: this.metrics.updateDelays.slice(-10), // 最近10次延迟
      
      // 用户行为统计
      userInterruptedOperations: this.metrics.userInterruptedOperations,
      userConfirmedUpdates: this.metrics.userConfirmedUpdates,
      userDelayedUpdates: this.metrics.userDelayedUpdates,
      interruptionRate: `${interruptionRate}%`,
      
      // 时间信息
      lastUpdateCheck: this.metrics.lastUpdateCheck,
      lastUpdateApplied: this.metrics.lastUpdateApplied,
      activeCriticalOperations: Array.from(this.metrics.criticalOperationStartTimes.keys())
    };
  }

  /**
   * 添加事件到上报队列
   */
  addToQueue(event) {
    if (!this.eventQueue) {
      this.eventQueue = [];
    }
    
    this.eventQueue.push({
      ...event,
      appId: this.options.appId,
      sessionId: this.getSessionId(),
      userAgent: navigator.userAgent,
      url: window.location.href
    });
    
    // 限制队列大小
    if (this.eventQueue.length > 100) {
      this.eventQueue = this.eventQueue.slice(-100);
    }
  }

  /**
   * 上报指标到分析平台
   * @param {boolean} sync - 是否同步上报
   */
  async flushMetrics(sync = false) {
    if (!this.eventQueue || this.eventQueue.length === 0) {
      return;
    }

    const eventsToSend = [...this.eventQueue];
    this.eventQueue = [];

    try {
      if (sync && navigator.sendBeacon) {
        // 使用 sendBeacon 同步上报（页面卸载时）
        const blob = new Blob([JSON.stringify({ events: eventsToSend })], {
          type: 'application/json'
        });
        navigator.sendBeacon(this.options.endpoint, blob);
      } else {
        // 异步上报
        const response = await fetch(this.options.endpoint, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ events: eventsToSend })
        });

        if (!response.ok) {
          console.warn('[UpdateMetricsMonitor] 指标上报失败:', response.status);
          // 重新加入队列，下次重试
          this.eventQueue.unshift(...eventsToSend);
        } else {
          console.log('[UpdateMetricsMonitor] 指标上报成功，数量:', eventsToSend.length);
        }
      }
    } catch (error) {
      console.error('[UpdateMetricsMonitor] 指标上报异常:', error);
      // 重新加入队列，下次重试
      this.eventQueue.unshift(...eventsToSend);
    }
  }

  /**
   * 保存指标到本地存储
   */
  saveToLocalStorage() {
    try {
      const data = {
        metrics: {
          ...this.metrics,
          // 将 Map 转换为数组以便序列化
          criticalOperationStartTimes: Array.from(this.metrics.criticalOperationStartTimes.entries())
        },
        timestamp: Date.now()
      };
      
      localStorage.setItem(this.options.localStorageKey, JSON.stringify(data));
    } catch (error) {
      console.warn('[UpdateMetricsMonitor] 本地存储失败:', error);
    }
  }

  /**
   * 从本地存储加载指标
   */
  loadFromLocalStorage() {
    try {
      const saved = localStorage.getItem(this.options.localStorageKey);
      if (saved) {
        const data = JSON.parse(saved);
        
        // 恢复基础指标
        this.metrics.updateAttempts = data.metrics.updateAttempts || 0;
        this.metrics.updateSuccesses = data.metrics.updateSuccesses || 0;
        this.metrics.updateFailures = data.metrics.updateFailures || 0;
        this.metrics.updateDelays = data.metrics.updateDelays || [];
        this.metrics.totalDelay = data.metrics.totalDelay || 0;
        this.metrics.userInterruptedOperations = data.metrics.userInterruptedOperations || 0;
        this.metrics.userConfirmedUpdates = data.metrics.userConfirmedUpdates || 0;
        this.metrics.userDelayedUpdates = data.metrics.userDelayedUpdates || 0;
        this.metrics.lastUpdateCheck = data.metrics.lastUpdateCheck || null;
        this.metrics.lastUpdateApplied = data.metrics.lastUpdateApplied || null;
        
        // 恢复 criticalOperationStartTimes - 正确处理 Map 的恢复
        if (data.metrics.criticalOperationStartTimes && Array.isArray(data.metrics.criticalOperationStartTimes)) {
          // 从数组恢复为 Map，同时过滤掉过期的操作（超过24小时）
          const now = Date.now();
          const twentyFourHoursAgo = now - (24 * 60 * 60 * 1000);
          const validEntries = data.metrics.criticalOperationStartTimes.filter(
            ([_, startTime]) => startTime > twentyFourHoursAgo
          );
          this.metrics.criticalOperationStartTimes = new Map(validEntries);
        } else {
          // 如果存储中没有该字段或格式不正确，初始化为空 Map
          this.metrics.criticalOperationStartTimes = new Map();
        }
        
        console.log('[UpdateMetricsMonitor] 从本地存储恢复指标成功');
      }
    } catch (error) {
      console.warn('[UpdateMetricsMonitor] 本地存储加载失败:', error);
      // 加载失败时保持默认值
      this.metrics.criticalOperationStartTimes = new Map();
    }
  }

  /**
   * 生成会话ID
   * 生成唯一的会话标识符，用于关联同一用户会话中的多个事件
   */
  getSessionId() {
    try {
      // 尝试从 sessionStorage 获取现有会话ID
      let sessionId = sessionStorage.getItem('update_monitor_session_id');
      
      // 如果不存在或已过期（超过24小时），创建新的会话ID
      if (!sessionId) {
        sessionId = this.generateSessionId();
        sessionStorage.setItem('update_monitor_session_id', sessionId);
        sessionStorage.setItem('update_monitor_session_start', Date.now().toString());
      } else {
        // 检查会话是否过期（24小时）
        const sessionStart = parseInt(sessionStorage.getItem('update_monitor_session_start') || '0', 10);
        const twentyFourHours = 24 * 60 * 60 * 1000;
        
        if (Date.now() - sessionStart > twentyFourHours) {
          // 会话过期，创建新的会话ID
          sessionId = this.generateSessionId();
          sessionStorage.setItem('update_monitor_session_id', sessionId);
          sessionStorage.setItem('update_monitor_session_start', Date.now().toString());
        }
      }
      
      return sessionId;
    } catch (error) {
      // 如果 sessionStorage 不可用，使用基于时间的随机ID
      console.warn('[UpdateMetricsMonitor] 无法访问 sessionStorage，使用临时会话ID:', error);
      return this.generateSessionId();
    }
  }

  /**
   * 生成新的会话ID
   * @private
   */
  generateSessionId() {
    // 使用时间戳 + 随机字符串生成唯一ID
    const timestamp = Date.now();
    const randomStr = Math.random().toString(36).substring(2, 15);
    const userAgentHash = this.hashString(navigator.userAgent.substring(0, 50));
    
    return `session_${timestamp}_${randomStr}_${userAgentHash}`;
  }

  /**
   * 简单的字符串哈希函数
   * @private
   */
  hashString(str) {
    let hash = 0;
    for (let i = 0; i < str.length; i++) {
      const char = str.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash = hash & hash; // 转换为32位整数
    }
    return Math.abs(hash).toString(36).substring(0, 8);
  }

  /**
   * 重置所有指标
   */
  reset() {
    this.metrics = {
      updateAttempts: 0,
      updateSuccesses: 0,
      updateFailures: 0,
      updateDelays: [],
      totalDelay: 0,
      userInterruptedOperations: 0,
      userConfirmedUpdates: 0,
      userDelayedUpdates: 0,
      lastUpdateCheck: null,
      lastUpdateApplied: null,
      criticalOperationStartTimes: new Map()
    };
    
    this.eventQueue = [];
    localStorage.removeItem(this.options.localStorageKey);
    console.log('[UpdateMetricsMonitor] 所有指标已重置');
  }
}

// 导出单例实例
export const updateMetricsMonitor = new UpdateMetricsMonitor();

// 与 UpdateManager 集成示例
export function integrateWithUpdateManager(updateManager) {
  // 监听更新管理器事件
  updateManager.onUpdateFound = (registration) => {
    updateMetricsMonitor.recordUpdateFound({
      version: registration.waiting?.scriptURL,
      isCriticalOperation: updateManager.isCriticalOperation
    });
  };

  updateManager.onUpdateSuccess = (details) => {
    updateMetricsMonitor.recordUpdateSuccess(details);
  };

  updateManager.onUpdateFailure = (error) => {
    updateMetricsMonitor.recordUpdateFailure(error);
  };

  // 监听关键操作
  const originalStart = updateManager.startCriticalOperation;
  const originalEnd = updateManager.endCriticalOperation;

  updateManager.startCriticalOperation = function(operationId) {
    updateMetricsMonitor.recordCriticalOperationStart(operationId);
    return originalStart.call(this, operationId);
  };

  updateManager.endCriticalOperation = function(operationId) {
    updateMetricsMonitor.recordCriticalOperationEnd(operationId);
    return originalEnd.call(this, operationId);
  };

  console.log('[UpdateMetricsMonitor] 已与 UpdateManager 集成');
}
```**使用示例：**

```javascript
// 1. 初始化监控器
import { updateMetricsMonitor, integrateWithUpdateManager } from './update-metrics-monitor.js';
import { useUpdateManager } from './useUpdateManager.js';

// 2. 与更新管理器集成
const updateManager = useUpdateManager();
integrateWithUpdateManager(updateManager);

// 3. 在关键节点记录指标
// 更新检查时
updateMetricsMonitor.recordUpdateCheck();

// 用户确认更新时
updateMetricsMonitor.recordUserConfirmedUpdate();

// 4. 获取并展示指标
const metrics = updateMetricsMonitor.getMetrics();
console.log('更新成功率:', metrics.successRate);
console.log('平均更新延迟:', metrics.avgUpdateDelay);
console.log('用户中断率:', metrics.interruptionRate);

// 5. 手动触发上报（通常在页面卸载或定期执行）
updateMetricsMonitor.flushMetrics();

// 6. 在管理面板中展示
function renderMetricsDashboard() {
  const metrics = updateMetricsMonitor.getMetrics();
  return `
    <div class="metrics-dashboard">
      <h3>更新监控指标</h3>
      <div>更新成功率: ${metrics.successRate}</div>
      <div>平均延迟: ${metrics.avgUpdateDelay}</div>
      <div>用户中断操作: ${metrics.userInterruptedOperations}</div>
      <div>活跃关键操作: ${metrics.activeCriticalOperations.join(', ') || '无'}</div>
    </div>
  `;
}

监控指标说明：

更新成功率：成功更新次数 / 总更新尝试次数 × 100%
平均更新延迟时间：从检测到更新到成功应用的平均时间
用户中断操作比例：因更新而中断的关键操作比例
用户确认率：用户主动确认更新的比例
关键操作持续时间：各类关键操作的平均耗时

数据上报策略：

实时上报 ：通过 flushMetrics() 异步上报到分析平台
本地缓存：使用 localStorage 持久化存储，防止数据丢失
页面卸载保护 ：使用 sendBeacon 确保页面关闭时数据不丢失
批量处理：事件队列批量上报，减少网络请求

集成建议：

将此监控模块与现有的 UpdateManager 集成
在管理后台展示关键指标仪表盘
设置告警阈值（如成功率低于95%时告警）
定期分析指标趋势，优化更新策略

7.3 调试工具

开发工具中的 Service Worker 面板
自定义更新日志与事件追踪
用户反馈收集机制

8. 最佳实践与常见陷阱

8.1 最佳实践

明确关键操作边界：不要过度保护非关键操作
提供用户控制权：让用户了解并控制更新时机
设置超时机制：避免更新无限期延迟
渐进式部署：先小范围验证再全量推送

8.2 常见陷阱与解决方案

陷阱1 ：更新延迟导致功能不一致
- 解决方案：API版本兼容性设计
陷阱2 ：Service Worker 缓存污染
- 解决方案：严格的缓存命名空间与清理策略
陷阱3 ：多标签页状态同步问题
- 解决方案：BroadcastChannel 或 localStorage 同步状态

9. 未来展望与进阶方向

AI驱动的智能更新：基于用户行为预测最佳更新时机
微前端架构下的更新策略：子应用独立更新与协调
边缘计算与CDN集成：更细粒度的资源更新控制
标准化提案：Web Platform 可能的原生支持

10. 总结

离线暂停更新策略的核心价值：用户体验与系统稳定的平衡
技术选型建议：根据应用复杂度选择合适方案
实施路线图：从基础检测到智能决策的渐进式优化
最终目标：让更新对用户"无感"，提升产品专业度与用户信任