前端埋点 SDK 的工程化落地：批量上报、失败重试与采样降噪

埋点看似只是"点一下按钮发一条请求"，真正落到生产环境，问题几乎都集中在三件事上：上报节奏不可控、失败数据不可恢复、数据量不可解释。本文从工程实现角度，讨论一个可在业务侧自建的前端埋点 SDK，覆盖队列模型、批量上报、失败重试、本地持久化与采样降噪五个核心模块，并给出可直接复用的代码骨架。

一、为什么在业务侧自建而不是直接接入第三方

第三方分析平台的默认实现有几个难以回避的约束：SDK 体积通常在 20KB 以上且难以按需裁剪；上报时机由平台决定，无法与业务的关键节点对齐；事件属性无法自动携带业务上下文，例如灰度分组、租户标识、页面栈深度。自建 SDK 的价值不在于"重造分析平台"，而在于把埋点变成一个可测试、可灰度的内部模块。

实践中的判断标准是：如果埋点需要与业务状态强耦合（例如下单漏斗需要携带购物车快照），或需要对上报量做成本控制，自建更合适；如果只需要 PV/UV 类基础统计，接入成熟平台成本更低。

二、事件模型：先定结构，再谈传输

所有问题的起点是事件结构。一个稳定的结构应当包含事件名、时间戳、页面标识、用户标识、会话标识与业务属性，且业务属性必须是可序列化的扁平常量，避免直接塞入 DOM 节点或类实例。

interface TrackEvent {
  event: string;          // 事件名，建议 domain.action 形式
  ts: number;             // 客户端时间戳，服务端需二次校准
  page: string;           // 路由标识，而非完整 URL
  uid?: string;           // 用户标识，未登录时缺省
  sid: string;            // 会话标识，用于漏斗串联
  props?: Record<string, string | number | boolean>;
}

把 page 设计成路由标识而不是完整 URL，是为了避免 query 中的临时参数把同一页面拆成上千个维度；把 props 限制为原始类型，是为了保证序列化结果稳定，避免上报前后结构不一致导致下游解析失败。

三、队列与批量上报

逐条上报会在页面交互密集时产生大量小请求，既浪费连接又容易触发服务端限流。批量上报的关键是"双触发条件"：数量阈值与时间窗口，先到先发。

class Reporter {
  private queue: TrackEvent[] = [];
  private timer: number | null = null;
  private readonly MAX_BATCH = 10;
  private readonly DELAY = 5000;

  push(e: TrackEvent) {
    this.queue.push(e);
    if (this.queue.length >= this.MAX_BATCH) {
      void this.flush();
      return;
    }
    if (this.timer === null) {
      this.timer = window.setTimeout(() => void this.flush(), this.DELAY);
    }
  }

  async flush() {
    if (this.timer !== null) {
      clearTimeout(this.timer);
      this.timer = null;
    }
    if (this.queue.length === 0) return;

    const batch = this.queue.splice(0, this.MAX_BATCH);
    try {
      await send(batch);
    } catch (err) {
      // 失败回填到队首，保证顺序且不丢数据
      this.queue.unshift(...batch);
    }
  }
}

这里有两个容易忽略的细节。其一，定时器应在队列由空变非空时创建，而不是在构造时用 setInterval 常驻，否则页面空闲期会持续空转。其二，失败时用 unshift 把批次放回队首而不是重新 push，可以保持事件的时间顺序，避免下游做漏斗分析时出现"后发生的事件先到达"。

四、页面卸载的兜底

用户关闭标签页时，队列中往往还有未发出的数据。此时异步 fetch 大概率被浏览器中断，可靠的做法是监听 visibilitychange 并使用 sendBeacon。

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState !== 'hidden') return;
  if (queue.length === 0) return;

  const body = new Blob([JSON.stringify(queue)], { type: 'application/json' });
  const ok = navigator.sendBeacon('/collect', body);
  if (ok) queue.length = 0;
});

选择 visibilitychange 而不是 beforeunload，是因为移动端浏览器在切换到后台时可能直接冻结页面，beforeunload 不一定会触发；而 visibilitychange 在切后台、切标签页、锁屏等场景下都能稳定触发。sendBeacon 本身有约 64KB 的载荷上限，超过会返回 false，因此需要判断返回值，失败时保留队列。

五、失败重试与本地持久化

网络抖动是常态，重试是必要的，但没有上限的重试会把一次服务端故障放大成雪崩。合理的策略是指数退避加次数上限：1 秒、2 秒、4 秒，最多三次；仍失败则落盘，等待下次启动回放。

const KEY = 'track_pending';
const TTL = 24 * 60 * 60 * 1000;
const LIMIT = 200;

function persist(list: TrackEvent[]) {
  try {
    const now = Date.now();
    const alive = list.filter((e) => now - e.ts < TTL);
    localStorage.setItem(KEY, JSON.stringify(alive.slice(-LIMIT)));
  } catch {
    // 隐私模式或配额超限，静默降级
  }
}

三个约束必须同时存在：TTL 过滤过期事件、条数上限防止无限增长、try/catch 兜住存储异常。在 Safari 隐私模式下 localStorage.setItem 会直接抛出 QuotaExceededError，未捕获会导致整个 SDK 初始化中断，这是线上最常见的低级事故之一。

六、采样降噪

并非所有事件都值得全量采集。错误类事件量小、价值高，应全量上报；曝光与滚动类事件量级极大，需要采样。采样时必须基于会话标识做哈希取模，而不是对每条事件独立随机。

function shouldSample(sid: string, rate: number) {
  let h = 0;
  for (let i = 0; i < sid.length; i++) h = (h * 31 + sid.charCodeAt(i)) | 0;
  return Math.abs(h) % 100 < rate;
}

原因很直接：如果对每条事件独立随机，同一次会话中的行为会部分丢失，漏斗分析的分母和分子不再对应，算出的转化率是失真的。按会话哈希取模可以保证"要么整个会话被采样，要么完全不被采样"，代价是样本量波动更大，但统计意义更清晰。

七、踩坑清单

• 在 beforeunload 里发起异步请求，数据必然丢失，应改用 sendBeacon。
• 重试不设上限，服务端故障期间请求量按指数增长，进一步压垮服务。
• 采样按事件随机而非按会话哈希，导致漏斗数据自相矛盾。
• localStorage 写满后未捕获异常，SDK 初始化直接失败。
• 直接使用客户端时间戳，未做服务端校准，跨时区用户的数据会出现顺序错乱。
• 把完整 URL 作为页面维度，query 参数把同一页面拆成大量稀疏维度。

八、小结

一个可用的埋点 SDK，复杂度并不在"发请求"，而在边界处理：队列什么时候发、发失败怎么办、页面关掉怎么办、数据太多怎么办。把批量上报、失败回填、卸载兜底、持久化上限与一致性采样这五件事做扎实，埋点数据才具备被业务信任的基础。建议在接入前先用一个内部灰度开关控制采样率，观察一周的上报量与端上耗时，再决定是否全量放开。