前端 fetch 怎样在页面卸载时发送小请求

页面关闭、刷新或跳转时，普通 fetch() 可能还没有把请求交给网络层，文档就已经被卸载了。适合收尾上报的做法是给请求加上 keepalive: true，让它在页面生命周期结束后仍有机会完成；但它只适合小型数据，不能把它当成大文件上传或可靠消息队列。

keepalive 解决的是“页面没了，请求还能不能继续发”的生命周期问题；真正的硬边界是请求体字节数和未完成请求的总预算。下面用 pagehide 发送一条短 JSON，并在进入请求前按 UTF-8 字节数做保守限制。

先分清页面卸载与请求完成

用户离开页面时，脚本不应依赖一个长时间等待的 Promise。keepalive 是 RequestInit 的布尔选项，设置后可以让关联请求在发起它的页面卸载后继续存活；它仍然是网络请求，不会把服务器响应变成页面可见的结果。

收尾事件可以使用 pagehide，它覆盖离开当前页面和进入浏览器缓存等场景。示例中的 payload 只放事件 ID、页面标识和时间戳，便于服务端去重；这些字段是示例业务数据，不代表某个站点已经真实接收。

在 pagehide 中发送一条小 JSON

把请求函数写成“只接受短字段、只负责发出”的小单元，调用方就不容易把表单、日志全文或二进制文件误塞进卸载请求。fetch 返回的 Promise 可以接住同步创建阶段的异常，但页面卸载后不要依赖它更新界面。

// 发送页面离开时的最小收尾事件；服务端应按 eventId 做幂等去重
function sendPageExitEvent() {
  const payload = {
    // 用稳定 ID 避免刷新和回退造成重复记账
    eventId: crypto.randomUUID(),
    page: location.pathname,
    leftAt: new Date().toISOString()
  };

  const body = JSON.stringify(payload);
  const bytes = new TextEncoder().encode(body).byteLength;

  // 64 KiB 是未完成 keepalive 请求体的规范预算，实际项目要留出余量
  if (bytes > 48 * 1024) {
    return;
  }

  void fetch('/telemetry/page-exit', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body,
    keepalive: true
  }).catch(() => {
    // 卸载阶段失败通常无法补救；不要在这里阻塞页面离开
  });
}

window.addEventListener('pagehide', sendPageExitEvent, { once: true });

这里用 48 KiB 而不是把预算用满，是为了给同时存在的其它 keepalive 请求和实现差异留出空间。TextEncoder 计算的是 UTF-8 字节数，不能用 JavaScript 字符串的 length 代替；中文、表情和转义后的 JSON 都可能让字节数变大。

请求体边界不是单次调用的万能上限

Fetch 标准对 keepalive 请求设置了有界预算：同一 fetch group 中仍未完成的 keepalive 请求，会把各自的请求体长度累计起来；当前请求与这部分累计值超过 64 KiB 时，网络抓取会失败。实际代码因此要同时控制单次请求大小、触发频率和并行中的收尾请求数量。

不要把“请求创建成功”当成“服务端已经落库”。页面离开后无法稳定展示错误，也不适合在回调里再次发同一条数据；服务端应使用 eventId 做幂等处理，并把不可接受的请求体大小作为普通错误记录下来。

兼容性与降级边界

MDN 将 keepalive 标记为 Baseline 2024，但旧设备和旧浏览器仍可能不支持。可以先用 Request.prototype 做能力判断；如果不支持，且数据是简单的 POST 通知，可以尝试 navigator.sendBeacon()。如果数据需要自定义方法、请求头或读取响应，就应让业务在页面仍存活时发送，不能假设卸载阶段一定有可用的替代方案。

// 能力不足时只对简单收尾数据降级到 sendBeacon
function sendExitWithFallback(body) {
  if ('keepalive' in Request.prototype) {
    // keepalive 支持自定义请求配置，仍要保留字节数限制
    return fetch('/telemetry/page-exit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body,
      keepalive: true
    });
  }

  // Beacon 只返回是否成功排入发送队列，不代表服务端已处理
  const queued = navigator.sendBeacon(
    '/telemetry/page-exit',
    new Blob([body], { type: 'application/json' })
  );
  return queued ? Promise.resolve() : Promise.reject(new Error('beacon queue full'));
}

这段降级只解决“浏览器没有 keepalive”这一层，不解决网络断开、服务端拒绝、用户强制终止进程等问题。若事件不可丢失，应在页面活跃时写入服务端或应用自己的可靠队列，卸载事件只作为补充通知。

常见问题

keepalive 能保证页面关闭后请求一定到达吗？

不能。它只允许请求超过页面生命周期继续执行，并受浏览器预算、网络状态和服务端处理影响；需要可靠交付时仍要设计服务端确认、重试或持久化队列。

为什么不能直接把整个 localStorage 发出去？

数据量可能超过 keepalive 的总预算，而且 JSON 序列化后还会产生额外字节。应该筛选必要字段、计算 UTF-8 字节数，并在页面还活跃时分批发送。

pagehide 和 beforeunload 应该选哪个？

收尾上报通常优先考虑 pagehide，因为它更贴合页面离开生命周期，也不要求弹窗或阻塞用户离开。不要用同步 XHR 或阻塞式等待来“保证”请求完成。