浏览器页面离开前怎么可靠上报：sendBeacon、fetch keepalive 与重复提交边界

用户关闭标签页、跳转路由或切到后台时，普通的异步请求可能还没发完就被浏览器终止。轻量、无需读取响应的离开页面上报，优先考虑 navigator.sendBeacon()；如果必须读取响应或使用更完整的请求配置，可以使用带 keepalive: true 的 fetch()，但要接受体积和生命周期约束。两者都不能替代服务端幂等，真正的可靠性要靠“事件 ID + 服务端去重 + 可观测结果”闭环。

先分清：要的是“尽量送达”还是“拿到响应”

sendBeacon 的调用结果只表示浏览器是否接受了这次排队请求，不表示服务器已经处理成功。它适合浏览时长、曝光、离开原因等小型事件，页面不用等待，也不用在回调里更新界面。

fetch({ keepalive: true }) 仍然是 Fetch 请求，可以读取状态码和响应内容，但请求会受到浏览器对 keepalive 数据量和生命周期的限制。不要把大段日志、文件或未压缩表单塞进离开页面钩子。

const eventId = crypto.randomUUID();
const payload = JSON.stringify({
  eventId,
  page: location.pathname,
  reason: "visibility-hidden",
  at: Date.now()
});

// 不需要响应：优先 Beacon
const queued = navigator.sendBeacon(
  "/telemetry/page-leave",
  new Blob([payload], { type: "application/json" })
);

// 需要读取响应时，改用 keepalive fetch
fetch("/telemetry/page-leave", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: payload,
  keepalive: true,
  credentials: "same-origin"
}).then(response => {
  if (!response.ok) throw new Error(`report failed: ${response.status}`);
});

页面离开时为什么要监听 visibilitychange

beforeunload 更适合处理“是否真的要离开”的交互，不适合作为通用埋点时机。移动端切换应用、系统回收页面等情况未必触发它。对不需要阻止离开的数据上报，通常在 visibilitychange 变为 hidden 时触发；如果业务还要覆盖页面被放入缓存的情况，可以补充 pagehide，但仍应通过事件 ID 防止两处监听重复发送。

let reported = false;

function reportOnce(reason) {
  if (reported) return;
  reported = true;
  const body = JSON.stringify({
    eventId: crypto.randomUUID(),
    reason,
    path: location.pathname,
    at: Date.now()
  });
  navigator.sendBeacon(
    "/telemetry/page-leave",
    new Blob([body], { type: "application/json" })
  );
}

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") reportOnce("hidden");
});
window.addEventListener("pagehide", () => reportOnce("pagehide"));

sendBeacon 的三个边界：方法、响应和体积

sendBeacon 面向异步 POST 上报，不能像普通 fetch 一样自由选择方法，也不会把服务端响应交给调用方。如果接口必须使用 PUT、需要自定义认证头或必须根据响应修改本地状态，就不应强行套 Beacon。

第二个边界是数据体积。浏览器会拒绝或无法保证过大的待发送数据；调用返回 false 时，代码应记录本地降级计数，不能把它当成服务端失败后无限重试的信号。页面离开阶段也不要做同步 XHR 或阻塞式重试。

keepalive fetch 怎么控制重复提交

keepalive 解决的是请求可能跨越页面生命周期继续发送，不是消息队列，也不是重试协议。对于同一个用户动作，点击处理器、visibilitychange 和 pagehide 可能各自触发一次，因此前端要做一次性保护，服务端还要按 eventId 做最终去重。

// 服务端伪代码：重复 eventId 返回第一次的结果
const old = await store.get(`telemetry:${eventId}`);
if (old) return json(old);

const result = await saveEvent({ eventId, page, reason, at });
await store.set(`telemetry:${eventId}`, result, { ttl: 86400 });
return json(result);

幂等记录的 TTL 应覆盖客户端可能重复发送的时间窗口。不要只按页面路径或用户 ID 去重，否则同一用户连续访问同一页面时会误丢真实事件。

一组能落地的验收方法

1. 在事件中固定输出 eventId，浏览器网络面板和服务端日志都保留它。
2. 正常点击离开、刷新、前进后退、切后台各测一次，确认服务端能收到但不会重复落库。
3. 把请求体逐步放大，记录 sendBeacon 返回值和 keepalive 请求的失败边界，不把某个浏览器的偶然成功当成容量承诺。
4. 断网后恢复、快速连续触发两次，确认页面不会因为同步等待卡住，服务端也不会把同一个事件记两遍。

常见误区与相关问题

sendBeacon 返回 true 就代表数据落库了吗？

不是。它只说明用户代理接受了这次请求，最终是否到达和落库仍要依靠服务端日志、幂等记录和抽样核对。

可以同时调用 sendBeacon 和 keepalive fetch 兜底吗？

不建议无条件双发，因为两次请求都可能到达。若确实要做降级，应让服务端以同一个事件 ID 幂等处理，并明确统计“已排队”和“已处理”两个指标。

什么时候应该做离线队列？

如果数据不能丢、体积较大或需要严格重试顺序，页面离开上报已经超出适用边界，应评估本地持久化、Service Worker 或服务端消息队列方案。

总结

页面离开前的上报选择可以压缩成一句话：无需响应的小事件用 sendBeacon，需要响应且数据很小才用 fetch keepalive；无论选哪一个，都给事件生成唯一 ID，并让服务端负责去重和验收。这样即使页面生命周期很短，也能把“浏览器接受请求”和“业务确实处理”区分开。