Service Worker background-sync 用法详解

Service Worker 的 Background Sync API 是实现“离线提交、联网自动重试”这一关键用户体验的利器，它能在网络恢复后无需用户干预、不依赖页面是否打开，智能触发后台同步任务；文章深入解析了其核心用法——从 HTTPS 环境与浏览器兼容性（Chrome/Edge 主流支持）等前提条件，到前端离线时注册同步任务、Service Worker 中监听并处理 sync 事件，再到结合 IndexedDB 持久化数据与幂等设计保障可靠性，并提供了时间戳追踪、重试上限控制、用户反馈和定期清理等实战技巧，帮你构建真正健壮、用户无感的离线优先应用。

Service Worker 的 Background Sync API 可以在用户恢复网络连接后，自动触发一次或多次后台同步任务，非常适合实现“离线提交、联网重试”的数据提交逻辑。它不依赖页面是否打开，只要 Service Worker 处于激活状态且浏览器支持，就能在合适时机执行重试。

前提条件与浏览器支持

Background Sync 目前仅在 Chrome、Edge（基于 Chromium）和部分 Android 浏览器中稳定支持，Firefox 和 Safari 尚未实现。使用前需确认：

• 站点必须通过 HTTPS（本地开发时 localhost 也允许）
• 已成功注册并激活 Service Worker
• 用户授予了网站“后台同步”权限（现代 Chrome 会隐式授予，无需显式请求）
• 同步事件名称需唯一，建议按业务类型命名（如 "submit-order"）

注册同步任务（离线时调用）

当用户点击提交但网络不可用时，不要直接报错，而是缓存数据并注册一个同步任务：

// 前端 JS（如表单提交处理）
async function submitForm(data) {
  if (navigator.onLine) {
    await sendToServer(data);
  } else {
    // 1. 本地持久化待提交数据（推荐使用 IndexedDB）
    await savePendingData(data);
    // 2. 注册后台同步（仅当 Service Worker 控制当前页面时有效）
    if ('serviceWorker' in navigator && navigator.serviceWorker.controller) {
      try {
        await navigator.serviceWorker.controller.sync.register('submit-form');
        console.log('Sync registered');
      } catch (err) {
        console.warn('Sync registration failed:', err);
      }
    }
  }
}

在 Service Worker 中监听 sync 事件

在 Service Worker 文件（如 sw.js）中监听 sync 事件，并执行实际的提交逻辑：

// sw.js
self.addEventListener('sync', event => {
  if (event.tag === 'submit-form') {
    event.waitUntil(
      handlePendingSubmissions()
    );
  }
});

async function handlePendingSubmissions() {
  const db = await openPendingDB(); // 打开 IndexedDB
  const pendingItems = await getAllPending(db);

  for (const item of pendingItems) {
    try {
      await fetch('/api/submit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(item.data)
      });

      // 提交成功 → 删除本地记录
      await deletePending(db, item.id);
    } catch (err) {
      // 失败不抛出，让系统后续重试（默认最多重试几次，由浏览器决定）
      console.warn('Submission failed, will retry later:', err);
    }
  }
}

注意：不要在 sync 事件中调用 event.preventDefault()；失败的同步不会自动重复注册，但浏览器会在后续网络恢复时再次触发同名 sync 事件（通常间隔逐渐拉长，最多尝试数次）。

增强可靠性的小技巧

• 添加时间戳和重试计数：在 IndexedDB 中存储每条待提交数据的创建时间与失败次数，超过阈值（如 5 次）可主动丢弃或上报异常
• 避免重复提交：后端需支持幂等性（例如用客户端生成的 UUID 作为请求 ID），防止多次 sync 触发重复写入
• 用户反馈可选：可在页面监听 controllerchange 或用 postMessage 从 SW 发送成功/失败消息，提示用户“已提交”或“仍在重试中”
• 清理机制：定期检查过期未提交项（如 >7 天），避免 DB 膨胀

今天关于《Service Worker background-sync 用法详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！