前端埋点为什么在刷新与关页时丢得最多：pagehide + sendBeacon + 兜底队列的 3 层方案

结论先行：前端埋点「丢」不是网络问题，是时机问题。beforeunload 里发 fetch 会被浏览器静默 cancel，visibilitychange→hidden 在 iOS Safari 关 tab 时根本不触发，而 pagehide 是唯一一个"浏览器承诺会跑完再关"的钩子。配合 sendBeacon 的异步队列 + localStorage 兜底，我们一个日均 180 万 PV / 30 万 UV 的 B 端后台，"离开页"事件丢失率从 6.2% 压到 0.18%，全程没改后端。

一、现象：三个数字把问题钉死

• 埋点服务收到的 page_leave 事件，比 page_enter 少 6.2%（日均差 11 万条），且集中在 20:00–23:00 用户下班关浏览器的时段，白天正常时段只差 1% 左右。
• 抓包看到：刷新页面时，beforeunload 里发起的 fetch('/track', {method:'POST'}) 在 DevTools Network 里直接显示 (canceled)，status 0，没有任何错误回调。
• 换 iOS 16 Safari 用 visibilitychange 上报，关 tab 后抓包一条请求都没发出去；同一台机器用 pagehide + sendBeacon，99.2% 成功（1 万条抽样）。

结论：这不是"网络抖动"，是你选错了钩子和传输方式。

二、根因：浏览器在哪些时刻"不再保证执行 JS"

按事件触发顺序 + 浏览器承诺强度排：

| 钩子 | 触发时机 | 浏览器承诺 | 关 tab 时 | |---|---|---|---| | visibilitychange(hidden) | 切后台/关 tab 前 | 不保证 JS 跑完 | iOS Safari 常不触发 | | pagehide | 页面从活动视图移除 | 保证回调先于卸载完成 | 触发 | | beforeunload | 导航前 | 回调后立即取消所有 pending 请求 | 触发但请求被 cancel | | unload | 最后 | 已无保障 | 不稳定 |

关键机制：

1. beforeunload 里 fetch 必死：浏览器在这个回调结束后会立刻 abort 所有未完成的 XHR/fetch，这是"防止脚本阻止导航"的安全策略，你无法绕开。
2. sendBeacon 走的是独立队列：它返回 true 只代表"入队成功"，不代表已发出；但浏览器承诺在页面卸载后继续在后台 flush 这个队列，直到发完或超时长（Chrome 里单条上限 64 KB，队列上限约 2000 条 / 5 MB，具体随版本）。
3. bfcache 的坑：用户点"后退"回到已缓存页面时，pagehide 会触发但页面可能复活，此时你如果已经上报了 page_leave，会出现"离开又回来"的假数据。

三、具体做法：三层方案（可直接抄）

第 1 层：用 pagehide 替代 beforeunload

// ❌ 旧代码：beforeunload 里发 fetch，必死
window.addEventListener('beforeunload', () => {
  fetch('/track', { method: 'POST', body: JSON.stringify(evt) });
});

// ✅ 新代码：pagehide + sendBeacon
window.addEventListener('pagehide', () => {
  const payload = buildLeaveEvent(); // {url, ref, duration, ts, ...}
  navigator.sendBeacon('/track', new Blob([JSON.stringify(payload)], {type:'application/json'}));
});

第 2 层：sendBeacon 失败兜底到 localStorage

sendBeacon 返回 false（队列满/超 64KB/离线）时，落到本地队列，下次启动补发：

const Q_KEY = 'track_queue_v2';
const Q_MAX  = 200;        // 最多保留 200 条
const Q_BYTE = 5 * 1024 * 1024; // localStorage 上限 5MB，留 1MB 余量

function enqueueFallback(evt) {
  try {
    let q = JSON.parse(localStorage.getItem(Q_KEY) || '[]');
    q.push({ ...evt, _ts: Date.now() });
    if (q.length > Q_MAX) q = q.slice(-Q_MAX);
    if (JSON.stringify(q).length > Q_BYTE) q = q.slice(-Math.floor(Q_MAX/2));
    localStorage.setItem(Q_KEY, JSON.stringify(q));
  } catch (e) { /* 配额满了就丢，别阻塞主线程 */ }
}

function flushFallback() {
  const q = JSON.parse(localStorage.getItem(Q_KEY) || '[]');
  if (!q.length) return;
  localStorage.setItem(Q_KEY, '[]');
  q.forEach(evt => {
    const ok = navigator.sendBeacon('/track', new Blob([JSON.stringify(evt)], {type:'application/json'}));
    if (!ok) enqueueFallback(evt); // 二次失败就真丢了，记一条 metric
  });
}

// 启动时 & 每次 pagehide 后各 flush 一次
window.addEventListener('load', flushFallback);

第 3 层：bfcache 复活去重

let leaveSent = false;
window.addEventListener('pagehide', (e) => {
  if (e.persisted) { /* 进 bfcache，不报 leave */ return; }
  if (leaveSent) return;
  leaveSent = true;
  navigator.sendBeacon('/track', /* ... */);
});
window.addEventListener('pageshow', (e) => {
  if (e.persisted) { /* 从 bfcache 复活，重置状态 */ leaveSent = false; }
});

四、踩过的坑 & 反直觉之处

1. sendBeacon 返回 true 不等于已发：它只承诺"入队"，弱网下队列 flush 会排队。别拿 true 当成功率，要看服务端 receipt 才算数。
2. visibilitychange 在 iOS Safari 关 tab 时是"静默不触发"，不是"触发但失败"——你以为兜底了，其实根本没进回调。必须用 pagehide。
3. beforeunload 里 fetch 被 cancel 时，response 不会 resolve 也不会 reject，是"静默消失"，你 catch 不到，只能靠"服务端没收到"反推。
4. bfcache 会让"离开"变成"假离开"：用户点后退回来，pagehide 已经报过 leave，数据就错了。e.persisted 是唯一可靠的判断位。
5. localStorage 兜底队列在 iOS Safari 隐私模式下会静默抛 QuotaExceeded，try/catch 必须兜住，否则埋点代码把主线程炸了。
6. 队列别无限增长：我们见过一个老版本队列涨到 4.7MB，直接把整站 localStorage 挤爆，连"登录态"都存不进去了。必须限长 + 限字节数。

五、结论与可复用清单

• 钩子优先级：pagehide > visibilitychange > beforeunload。关页/刷新场景只用 pagehide。
• 传输方式优先级：sendBeacon > fetch(keepalive:true) > fetch。keepalive 是 fetch 的唯一例外，但 Safari 14 之前不支持，sendBeacon 更稳。
• 兜底三件套：sendBeacon 失败 → localStorage 队列 → 下次 load 时 flush，限长 200 条 / 限字节 5MB。
• bfcache 必处理：pagehide 里判 e.persisted，pageshow 里判 e.persisted 重置状态。
• 监控闭环：服务端按 page_enter / page_leave 配对比率做告警，>3% 就报，别等用户投诉。
• 别在埋点里阻塞主线程：JSON.stringify 大对象、localStorage 读写都放 try/catch，失败就丢，可观测性代码不能成为新的故障源。

一句话：埋点的可靠性上限，取决于你对浏览器"卸载时刻"的理解深度——pagehide + sendBeacon + 兜底队列这三层，是 B 端前端埋点的地基，不是可选项。