Background Sync 延迟提交离线表单数据

我第一次把离线表单接进 Background Sync 时，最容易犯的错是把“稍后发送”理解成了“浏览器会替我保存数据”。实际上，Background Sync 只负责在合适的网络时机唤醒 Service Worker；表单数据是否能在刷新、关闭页面之后继续存在，还得由自己的本地 outbox 负责。

比较稳妥的组合是：提交动作先把一条可重试记录写入 IndexedDB，再注册一个稳定的同步标签；Service Worker 收到 sync 事件后逐条发送，成功才删除，暂时失败就保留。下面按我实际落地时的顺序，把这条链路拆开。

先把页面重试和后台同步分开

Background Synchronization API 依赖 Service Worker，通常只能在 HTTPS 等安全上下文中使用，而且目前不是所有主流浏览器都支持。它的价值不是“让请求永不失败”，而是把一次发送机会从当前页面生命周期里解耦出来。

因此我会把职责分成三层：

• 表单页面：收集输入、生成任务 ID、把任务写入 outbox。
• 同步注册：用一个稳定的 tag 告诉浏览器“有待发送任务”。
• Service Worker：读取队列、发送请求、依据结果删除或保留任务。

如果只在页面里调用 fetch 失败后立刻重试，用户关掉页面就没有后续执行者；如果只注册同步却没有持久化数据，Service Worker 被唤醒时又找不到要发送的内容。这两个问题要一起解决。

把离线表单先写进可恢复的 outbox

我更倾向于把 IndexedDB 当作 outbox，而不是把整张表单塞进某个内存变量。记录至少需要任务 ID、表单数据、创建时间和尝试次数。任务 ID 后面还可以作为服务端幂等键，避免网络超时后重发造成重复提交。

const OUTBOX_DB = "offline-form-db";
const OUTBOX_STORE = "outbox";

function openOutbox() {
  return new Promise((resolve, reject) => {
    // 使用版本号创建对象仓库；升级逻辑只负责准备待发送数据的存储空间。
    const request = indexedDB.open(OUTBOX_DB, 1);
    request.onupgradeneeded = () => {
      const db = request.result;
      if (!db.objectStoreNames.contains(OUTBOX_STORE)) {
        // 任务 ID 作为主键，保证同一任务不会因为重复点击而被覆盖成多条。
        db.createObjectStore(OUTBOX_STORE, { keyPath: "id" });
      }
    };
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

async function enqueueForm(formData) {
  const db = await openOutbox();
  const task = {
    // 这个 ID 同时可以传给服务端做幂等键。
    id: crypto.randomUUID(),
    payload: Object.fromEntries(formData),
    createdAt: Date.now(),
    attempts: 0
  };
  await new Promise((resolve, reject) => {
    const tx = db.transaction(OUTBOX_STORE, "readwrite");
    tx.objectStore(OUTBOX_STORE).put(task);
    tx.oncomplete = resolve;
    tx.onerror = () => reject(tx.error);
  });
  db.close();
  return task.id;
}

这里的关键不是 API 写法，而是“入队成功”要先于“注册同步”。如果浏览器暂时不支持 Background Sync，outbox 仍然可以给当前页面或下一次打开页面的前台重试使用。

注册一个稳定的同步标签

表单入队后，页面拿到已经 ready 的 Service Worker 注册对象，再尝试注册一个固定标签。标签表达的是“这类队列有工作要做”，不必为每一条表单创建一个标签，否则很容易让注册管理变复杂。

async function scheduleOutboxSync() {
  const registration = await navigator.serviceWorker.ready;
  const syncManager = registration.sync;

  // sync 属性或 register 方法缺失时，交给前台重试兜底，不假装已经安排成功。
  if (!syncManager || typeof syncManager.register !== "function") {
    return { scheduled: false, reason: "background-sync-unsupported" };
  }

  try {
    // 固定 tag 让多次提交合并到同一个同步任务里。
    await syncManager.register("offline-form-outbox");
    return { scheduled: true };
  } catch (error) {
    // 注册可能因权限、上下文或浏览器策略失败，调用方应保留 outbox。
    return { scheduled: false, reason: error.message };
  }
}

async function submitOfflineTolerantForm(form) {
  const id = await enqueueForm(new FormData(form));
  const result = await scheduleOutboxSync();
  if (!result.scheduled) {
    // 这里只触发一次前台尝试，真正的数据仍保留在 outbox 中。
    await flushOutboxInPage();
  }
  return id;
}

如果希望在开发阶段观察注册情况，可以调用 registration.sync.getTags() 读取当前标签。生产代码不要把它当成“服务器已收到”的证明，它只说明浏览器登记了一个待处理的同步请求。

让 Service Worker 只负责消费队列

Service Worker 的 sync 事件是整条链路的后台入口。事件处理器要用 event.waitUntil 托住异步工作，否则事件生命周期结束后，发送请求可能还没有完成。

self.addEventListener("sync", (event) => {
  // 只消费本应用登记的标签，避免不同队列互相干扰。
  if (event.tag === "offline-form-outbox") {
    event.waitUntil(flushOutbox());
  }
});

async function flushOutbox() {
  const tasks = await listOutboxTasks();
  for (const task of tasks) {
    try {
      const response = await fetch("/api/forms", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          // 让服务端能识别重试，而不是把同一表单当成新数据。
          "Idempotency-Key": task.id
        },
        body: JSON.stringify(task.payload)
      });
      if (!response.ok) {
        // 4xx/5xx 都不直接删除，按业务策略决定是否延后重试。
        throw new Error(`submit failed: ${response.status}`);
      }
      await deleteOutboxTask(task.id);
    } catch (error) {
      // 网络暂时不可用时保留任务，让下一次 sync 或前台打开继续处理。
      await markOutboxAttempt(task.id, error.message);
      throw error;
    }
  }
}

示例中的 listOutboxTasks、deleteOutboxTask 和 markOutboxAttempt 只是对 IndexedDB 读写的封装。真正实现时，我会把它们和页面端共用同一个数据库版本协议，避免页面升级了仓库结构而 Worker 仍按旧字段读取。

把“发送成功”和“暂时失败”分成两条路

我在联调时最容易忽略的是 HTTP 语义。网络恢复并不代表服务端一定接受了请求：鉴权失效、表单校验失败和服务端暂时不可用，应该有不同的处理方式。

对我来说，最重要的工程约束是服务端幂等：同一个任务 ID 重试多次，最多产生一次业务写入。仅靠客户端删除记录并不能解决“请求已到达但响应丢失”的窗口。

兼容性和降级要提前写进流程

MDN 当前把 Background Synchronization API、ServiceWorkerRegistration.sync 和 SyncManager 都标为 Limited availability，并且要求安全上下文。也就是说，不能把“注册成功”当成所有用户都能得到的默认能力。

我的降级顺序通常是：

1. 先写入 IndexedDB，确保任务不依赖页面是否继续打开。
2. 支持 Background Sync 时注册固定 tag。
3. 不支持或注册失败时，在当前页面监听 online，或在下次打开页面时主动 flush。
4. 对超过重试次数的任务展示“需要重新确认”的状态，而不是无休止请求。

这样即使浏览器没有后台同步，功能仍然是“可恢复但体验略降级”，而不是整条表单链路不可用。

最后用四个问题检查实现

• 数据问题：页面关闭后，待发送表单还在 IndexedDB 中吗？
• 注册问题：是否使用稳定 tag，并检查了 registration.sync 是否存在？
• 消费问题：Worker 是否用 event.waitUntil 等待队列处理，成功才删除？
• 业务问题：服务端是否按任务 ID 做幂等，4xx 和 5xx 是否有不同策略？

Background Sync 最适合“可以延迟、但不能轻易丢失”的表单和 outbox 任务。它不是消息队列，也不是跨浏览器的可靠投递承诺；把数据持久化、同步唤醒、失败策略和服务端幂等分别做好，才是一套真正能经受网络波动的实现。

相关问题

• Background Sync 注册失败时，应该先查安全上下文、Service Worker 状态还是浏览器支持？
• 为什么要把任务写入 IndexedDB，而不是只保存在页面变量里？
• Service Worker 重试时，如何避免服务端重复创建订单或留言？
• Background Sync 不可用时，怎样设计 online 事件和下次打开页面的前台补偿？