H5 埋点数据上报怎么做：批量合并、失败重试与采样控制

H5 页面做数据上报，最常踩的坑是"上报本身拖垮了页面"：每个事件一条请求，用户滚几下页面就发出几十个请求；弱网下请求排队，把正常业务请求都堵住；后端偶尔抖动，埋点数据悄悄丢一半还没人知道。埋点上报的正确姿势不是"发得越多越准"，而是批量合并、失败重试、按需采样。本文讲清一套可抄走的前端数据上报方案。

一、先定原则：上报不能影响用户体验

埋点上报在架构上是"尽力而为"：丢了 1% 的数据可接受，但因此卡了页面不可接受。所以三个核心约束：

不阻塞主流程：上报走异步，绝不参与用户可感知的交互链路 不占关键带宽：弱网下自动降级（减小批量、停图、只保关键事件） 可丢但可追：服务端要能识别缺口，能补采就补采

二、批量合并：攒一批再发

单个事件一条请求是最差实践。正确做法是攒批：事件先进内存队列，达到阈值（如 20 条）或间隔（如 5 秒）才打包成一条 POST 发出去。

class Tracker {
  constructor() {
    this.queue = [];
    this.MAX = 20;          // 批量上限
    this.INTERVAL = 5000;   // 攒批窗口
    this._timer = null;
    this._start();
  }
  track(event) {
    this.queue.push({ ...event, ts: Date.now() });
    if (this.queue.length >= this.MAX) this.flush();
  }
  flush() {
    if (!this.queue.length) return;
    const batch = this.queue.splice(0);
    // sendBeacon 在页面卸载时也能送达，且不阻塞主线程
    navigator.sendBeacon('/api/track', JSON.stringify({ events: batch }));
  }
  _start() {
    setInterval(() => this.flush(), this.INTERVAL);
    document.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'hidden') this.flush();
    });
  }
}

关键点：用 navigator.sendBeacon 而不是 fetch——它在页面关闭时也能把数据送出去，且不参与渲染阻塞；visibilitychange 到 hidden 时强制 flush，避免最后一批事件丢失。

三、失败重试：指数退避，别死磕

弱网/后端抖动时请求会失败。重试策略要"够坚持但不过分"：

async function sendWithRetry(payload, retries = 3) {
  for (let i = 0; i <= retries; i++) {
    try {
      const ok = await fetch('/api/track', {
        method: 'POST',
        body: JSON.stringify(payload),
        keepalive: true,
      });
      if (ok.ok) return true;
    } catch (e) { /* 网络错误，进入退避重试 */ }
    await sleep(1000 * Math.pow(2, i)); // 1s、2s、4s 指数退避
  }
  // 重试仍失败：写本地暂存（localStorage/IndexedDB），下次进入再补
  stashToLocal(payload);
  return false;
}

要点：

• 指数退避 + 抖动：1s/2s/4s，避免整站同时重试打爆后端。
• 三次失败就落地：把批次写进 IndexedDB（本地存储有容量上限），下次会话启动时补发，别在页面上无限重试。
• 超时兜底：单次请求设 5-10s 超时，别让失败请求占住连接。

四、采样控制：大数据量下只报一部分

页面量大、事件多时，全量上报是浪费。常用三种采样：

// 按用户哈希采样：同一用户行为轨迹完整，跨事件可关联
function shouldSample(userId, rate = 0.1) {
  let h = 0;
  for (const c of String(userId)) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return (h % 100) / 100 < rate;
}

核心原则：采样的目的是在"够分析"和"别浪费"之间取平衡——关键业务事件（下单、支付、注册）永远全量，高频行为事件（滚动、曝光、悬停）才采样。

五、踩坑清单

六、工程落地建议

数据上报的落地顺序：先上"攒批 + sendBeacon"（改动最小、收益最大），再加重试和本地暂存（保证数据完整），最后按事件类型分级——关键事件全量、高频事件采样。后端要配套一个简单的接收接口（幂等：按事件 id 去重）和缺口监控（每日事件量、失败率、补发量），数据链路才算闭环。这套方案同样适用于任何需要"前端采集 → 服务端汇总"的场景，比如访问统计、性能监控、AB 实验数据回传。

补充两个容易被忽略的细节：一是事件格式要预留版本字段（v: 1），后续字段调整时服务端能兼容新旧两种结构，避免升级一次丢一批历史数据；二是批量接口要做体积上限（如单批 100KB），超限拆批，防止个别大字段把整批请求打爆。这两点和攒批、重试、采样放在一起，前端上报链路才算完整。

七、复盘清单

• 事件是否攒批发送、是否用 sendBeacon
• 页面关闭/切后台是否强制 flush
• 失败是否有退避重试和本地暂存补发
• 是否有超时兜底、重试是否有上限
• 高频事件是否采样、关键事件是否全量
• 服务端是否幂等去重、是否有缺口监控

结语

H5 埋点上报的本质是"在数据完整性和资源开销之间找平衡"：批量合并省请求，失败重试保完整，采样控制控成本，sendBeacon 保证页面关闭也不丢。把这四件事做好，上报就从"拖慢页面的负担"变成"安静可靠的数据管道"。

以上为通用前端工程实践分享，仅作技术交流。