手把手搭一套前端监控采集 SDK

大家好 👋，我是 Moment，目前正在使用 Next.js、NestJS、LangChain 开发 DocFlow。这是一个面向 AI 场景的协同文档平台，集成了基于 Tiptap 的富文本编辑、NestJS 后端服务、实时协作与智能化工作流等核心模块。

在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性能优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。

如果你对 AI 全栈开发、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐

完整的前端监控平台通常分成三块：采集与上报、整理与存储、展示与分析。本文只讲第一块，从 0 搭一个可运行的埋点 SDK，并把指标采集方式对齐到当前浏览器与 Core Web Vitals 的常见做法。

名字会影响记忆和传播。这里把 SDK 叫做"四维"，英文 four-dimension，简写 FD，寓意尽量用上帝视角看清页面里发生的事。下文用 TypeScript 写示例，便于类型即文档。

自研采集层还要提前想好几条边界：是否采集可能含个人信息的字段、是否对错误栈与 URL 做脱敏、是否在低端机做采样。这些决定往往比多写一个 observer 更影响能不能上线。

整体结构

采集侧可以拆成四件事：配置、缓存与上报策略、各类 observer 与事件钩子、统一入口类。数据流与模块边界可以对照下图来记，和下面 Mermaid 图表达的是同一条主线。

如下图所示。

从页面事件到内存队列，再到空闲或离开时发往服务端的一整条链路。

配置与入口类

业务侧只需要改上报地址、应用标识等。配置对象建议可合并覆盖，避免散落魔法字符串。可预留 release、environment 字段，方便和后端版本聚类对齐。userId 若涉及合规，建议只传哈希后的业务 id，或默认不传，由登录域自行下发自洽标识。

在 config.ts 中集中维护默认值，并导出 setConfig，便于在业务入口覆盖：

export interface MonitorConfig {
  reportUrl: string;
  appId: string;
  userId?: string;
  projectName?: string;
  release?: string;
  environment?: "development" | "staging" | "production";
  sampleRate?: number;
}

const config: MonitorConfig = {
  reportUrl: "http://localhost:8000/report",
  appId: "fd-example",
  projectName: "fd-example",
  environment: "development",
  sampleRate: 1,
};

export function setConfig(partial: Partial<MonitorConfig>): void {
  Object.assign(config, partial);
}

export function getConfig(): Readonly<MonitorConfig> {
  return config;
}

FourDimension 负责在构造时拉起各模块。初始化不要依赖构造参数时，可以保持无参构造，只在 init 里注册监听，避免重复调用时重复挂钩子。

import { initPerformance } from "./performance";
import { initBehavior } from "./behavior";
import { initError } from "./error";

export class FourDimension {
  private inited = false;

  init(): void {
    if (this.inited) return;
    this.inited = true;
    initPerformance();
    initError();
    initBehavior();
  }
}

业务里建议异步加载 SDK 脚本，初始化时 new FourDimension().init() 即可。若脚本可能被多次执行，务必保留类似 inited 的幂等守卫，否则 fetch 会被包一层又一层。

上报通道 sendBeacon、图片打点与 XHR

navigator.sendBeacon 适合监控：异步、不抢主线程、在页面卸载时仍有机会发出。注意它发的是 POST，适合带 Blob 指定 Content-Type，而不是假设服务端只收 GET 查询串。

限制也要心里有数：无响应体、旧环境可能不存在、单次 payload 有实际上限（常见讨论量级在数十 KB，宜压 body 体积）。实践里常见优先级是 sendBeacon 优先，其次 1x1 图片 GET（数据需压缩且控制长度），再次带 keepalive: true 的 fetch 或 XMLHttpRequest。sendBeacon 返回 false 说明浏览器拒绝排队，应立刻换通道。

下面封装一个带降级的 sendReport。sendBeacon 分支用 Blob 传 JSON，图片分支再把数据塞进查询参数（注意浏览器对 URL 长度的限制）。

export function isSupportSendBeacon(): boolean {
  return (
    typeof navigator !== "undefined" &&
    typeof navigator.sendBeacon === "function"
  );
}

export function reportImage(url: string, payload: unknown): void {
  const qs = encodeURIComponent(JSON.stringify(payload));
  const img = new Image();
  img.src = `${url}?reportData=${qs}`;
}

export function reportWithXhr(url: string, body: string): void {
  const xhr = new XMLHttpRequest();
  xhr.open("POST", url);
  xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
  xhr.send(body);
}

export function sendReport(url: string, body: string): void {
  if (isSupportSendBeacon()) {
    const blob = new Blob([body], { type: "application/json" });
    const ok = navigator.sendBeacon(url, blob);
    if (ok) return;
  }
  reportImage(url, JSON.parse(body) as unknown);
}

真实项目里可以在 sendBeacon 返回 false 时再尝试 XHR，把失败样本写入 sessionStorage 下次补发。接收端要核实：网关是否允许 Content-Type: application/json 的 POST，是否对 OPTIONS 预检放行，否则 beacon 在跨域场景会静默失败，需在 Network 面板核对状态码。

上报降级顺序若画成一张小抄，方便和运维对口径。

如下图所示。

三种通道的优先顺序与跨域核对点。

缓存与上报时机

目标是对主线程影响尽量小。常见组合是：

• 内存里先攒一批，再批量上报
• 用 requestIdleCallback 在空闲时 flush，不支持时用 setTimeout 兜底
• 页面离开时把剩余队列一次性发出

离开页面时优先依赖 pagehide 与 visibilitychange，比单纯 beforeunload 更稳，尤其在移动端后台化场景。visibilitychange 在标签隐藏时就能先 flush 一轮，pagehide 在真正离开时再做最后一跳。两个事件都可能触发 flush 时，要么在 flushQueue 内做"空队列直接返回"，要么加发送中锁，避免重复上报同一批。

从 bfcache 恢复的页面会再走 pageshow，persisted 为 true 时会话可能延续，停留时长统计要把可见时间分段累加，不能假设一次进页到一次离开。

type ReportPayload = Record<string, unknown>;

const queue: ReportPayload[] = [];
let flushTimer: ReturnType<typeof setTimeout> | null = null;

export function enqueue(payload: ReportPayload): void {
  queue.push(payload);
}

export function flushQueue(reportUrl: string, immediate = false): void {
  if (!queue.length) return;
  const batch = queue.splice(0, queue.length);
  const body = JSON.stringify({ batch });
  if (immediate) {
    sendReport(reportUrl, body);
    return;
  }
  const run = () => sendReport(reportUrl, body);
  if (typeof requestIdleCallback === "function") {
    requestIdleCallback(run, { timeout: 3000 });
  } else {
    setTimeout(run, 0);
  }
}

export function scheduleFlush(reportUrl: string, delayMs = 2000): void {
  if (flushTimer) clearTimeout(flushTimer);
  flushTimer = setTimeout(() => {
    flushTimer = null;
    flushQueue(reportUrl, false);
  }, delayMs);
}

export function bindLifecycleFlush(reportUrl: string): void {
  const onHide = () => {
    if (document.visibilityState === "hidden") {
      flushQueue(reportUrl, true);
    }
  };
  window.addEventListener("pagehide", () => flushQueue(reportUrl, true));
  document.addEventListener("visibilitychange", onHide);
}

getCache 若要对调用方返回快照，需要深拷贝避免外部改数组。深拷贝实现注意处理循环引用以外的普通 JSON 友好结构即可。

性能指标用最新采集思路

PerformanceObserver 仍是采集绘制与布局类指标的主力，buffered: true 让你晚注入脚本也能拿到已经发生过的条目。导航类指标优先读 PerformanceNavigationTiming，比自己在事件里 performance.now() 更贴近浏览器统计。

在挂 observer 之前可以用静态方法探测当前环境到底支持哪些 entryTypes，避免 observe 直接抛错。下面是一段可放进工具模块的探测逻辑。

export function supportedPerfTypes(): string[] {
  if (typeof PerformanceObserver !== "function") return [];
  return PerformanceObserver.supportedEntryTypes ?? [];
}

export function canObserve(type: string): boolean {
  return supportedPerfTypes().includes(type);
}

在 Chrome DevTools 的 Performance 或 Lighthouse 里跑一遍同页，把面板里的 LCP、CLS 与 SDK 打上去的值对比，数量级应一致。若差一个数量级，先查是否重复统计、是否在 iframe 里采集、是否混用了导航时间与绘制时间。

与 Core Web Vitals 对齐

截至 Google 面向站长的公开说明，Core Web Vitals 核心指标是 LCP、INP、CLS。FID 已被 INP 取代，自研 SDK 仍可同时上报 FID 做历史对比，但产品解读应以 INP 为主。

指标	含义	推荐采集方式
LCP	视口内最大内容绘制完成时刻	PerformanceObserver，type: 'largest-contentful-paint'，通常取最后一次有效条目
INP	交互到下一帧绘制的延迟分布	PerformanceObserver，type: 'interaction'（需较新 Chromium），或引入 web-vitals 库
CLS	累计布局偏移	PerformanceObserver，type: 'layout-shift'，且只统计 hadRecentInput === false 的条目并累加 value

FP 与 FCP 仍可通过 type: 'paint' 观察，用于诊断首屏是否"空刷背景"与"首现有意义内容"的差异。

三个核心指标与采集入口的关系，适合印在团队 wiki 首页当速查图。

如下图所示。

LCP、INP、CLS 与对应 observer 类型名称的对应关系。

paint 与首屏绘制

下面示例合并监听 first-paint 与 first-contentful-paint，并在拿到 FCP 后断开，避免重复回调。若你希望两种 paint 都上报，应在两种都见到后再 disconnect，或干脆不断开、由服务端按 paintName 去重。

import { enqueue, scheduleFlush } from "./queue";
import { getConfig } from "./config";

function safeObserverSupported(): boolean {
  return typeof PerformanceObserver !== "undefined";
}

export function observePaint(): void {
  if (!safeObserverSupported()) return;
  const obs = new PerformanceObserver((list) => {
    for (const entry of list.getEntries()) {
      if (
        entry.name !== "first-paint" &&
        entry.name !== "first-contentful-paint"
      )
        continue;
      const json = entry.toJSON();
      enqueue({
        type: "performance",
        subType: "paint",
        paintName: entry.name,
        startTime: json.startTime,
        pageURL: location.href,
      });
      if (entry.name === "first-contentful-paint") {
        obs.disconnect();
        scheduleFlush(getConfig().reportUrl);
        break;
      }
    }
  });
  obs.observe({ type: "paint", buffered: true });
}

LCP 在页面生命周期内可能更新，规范语义是"最后一个汇报的 LCP 条目代表当前候选"。简单实现可以在回调里每次都上报最新一条，由服务端取同会话最后一次，或在客户端只保留最大 startTime 的那条再上报。注意 LCP 回调触发时 entry.element 可能已被移除，DOM 引用要谨慎，上报 tagName 与资源 URL 即可。

export function observeLcp(): void {
  if (!safeObserverSupported()) return;
  const obs = new PerformanceObserver((list) => {
    const entries = list.getEntries() as PerformanceEntry[];
    const last = entries[entries.length - 1] as LargestContentfulPaint &
      PerformanceEntry;
    const json = last.toJSON();
    enqueue({
      type: "performance",
      subType: "lcp",
      startTime: json.startTime,
      element: last.element?.tagName,
      url: "url" in last ? String((last as { url?: string }).url ?? "") : "",
      pageURL: location.href,
    });
    scheduleFlush(getConfig().reportUrl);
  });
  obs.observe({ type: "largest-contentful-paint", buffered: true });
}

上面用到 LargestContentfulPaint 时，若项目 lib.dom 较旧，可把 last 标成 PerformanceEntry 并谨慎读取可选字段。

CLS 与 INP

CLS 需要过滤用户操作附近的偏移，避免把有意交互造成的布局变化算成体验问题。

export function observeCls(): void {
  if (!safeObserverSupported()) return;
  let clsScore = 0;
  const obs = new PerformanceObserver((list) => {
    for (const entry of list.getEntries() as PerformanceEntry[]) {
      const ls = entry as LayoutShift & {
        hadRecentInput?: boolean;
        value?: number;
      };
      if (ls.hadRecentInput) continue;
      clsScore += ls.value ?? 0;
      enqueue({
        type: "performance",
        subType: "cls",
        value: ls.value,
        cumulativeLayoutShift: clsScore,
        pageURL: location.href,
      });
    }
    scheduleFlush(getConfig().reportUrl);
  });
  obs.observe({ type: "layout-shift", buffered: true });
}

INP 依赖 type: 'interaction' 的 PerformanceObserver，浏览器支持面仍在演进。生产环境若要省心，可直接使用 web-vitals 包，它会在不支持时降级或给出兼容策略。最小接入示意如下，真实项目里把 console.log 换成 enqueue 即可。

import { onINP } from "web-vitals";

onINP((metric) => {
  const v = metric.value;
  console.log("INP ms", v);
});

自研最小实现可以封装为"支持则订阅，不支持则不上报"，避免把未定义行为写死进业务。

导航时间与 DOMContentLoaded、load

更稳的做法是读取 performance.getEntriesByType('navigation')[0]，得到 PerformanceNavigationTiming，用相对 fetchStart 或 startTime 的各阶段时刻算 DNS、TCP、TTFB、DOM 解析等。字段含义以 MDN 上的 PerformanceNavigationTiming 为准，换公式前用一次 console.table 把 nav 打出来核对。

export function collectNavigationTiming(): void {
  const [nav] = performance.getEntriesByType(
    "navigation",
  ) as PerformanceNavigationTiming[];
  if (!nav) return;
  enqueue({
    type: "performance",
    subType: "navigation",
    dns: nav.domainLookupEnd - nav.domainLookupStart,
    tcp: nav.connectEnd - nav.connectStart,
    ttfb: nav.responseStart - nav.requestStart,
    domContentLoaded: nav.domContentLoadedEventEnd - nav.fetchStart,
    load: nav.loadEventEnd - nav.fetchStart,
    pageURL: location.href,
  });
  scheduleFlush(getConfig().reportUrl);
}

可在 load 事件触发后再调用一次，确保 loadEventEnd 已非 0。单页应用在客户端路由切换时不会产生新的 navigation 条目，若要监控"软导航"，需要结合框架路由钩子或 Performance API 里仍在演进的软导航相关能力单独设计，不能把 PV 和导航耗时混在一条 navigation 记录里硬解释。

资源耗时

资源条目用 type: 'resource'。注意不要在每个 entry 上都 disconnect，否则只会收到第一条资源。更合理的是页面 load 后一次性读取 performance.getEntriesByType('resource')，或长期观察但在 disconnect 前处理完整批次。

跨域资源若没有正确的 Timing-Allow-Origin，多数细粒度时长在浏览器里会被抹成 0，这是安全策略不是 SDK 坏了。核实方式是对比同源静态资源与 CDN 资源的 transferSize、domainLookupStart 等是否突然全 0。

export function observeResources(): void {
  if (!safeObserverSupported()) return;
  const obs = new PerformanceObserver((list) => {
    for (const entry of list.getEntries() as PerformanceResourceTiming[]) {
      enqueue({
        type: "performance",
        subType: "resource",
        name: entry.name,
        initiatorType: entry.initiatorType,
        duration: entry.duration,
        dns: entry.domainLookupEnd - entry.domainLookupStart,
        tcp: entry.connectEnd - entry.connectStart,
        ttfb: entry.responseStart - entry.requestStart,
        protocol: entry.nextHopProtocol,
        transferSize: entry.transferSize,
        encodedBodySize: entry.encodedBodySize,
        decodedBodySize: entry.decodedBodySize,
        pageURL: location.href,
      });
    }
    scheduleFlush(getConfig().reportUrl);
  });
  obs.observe({ type: "resource", buffered: true });
}

若担心资源量过大，可在客户端按域名白名单或按耗时阈值过滤后再入队。也可按 config.sampleRate 随机丢弃非错误样本，只保留长尾。

接口耗时：fetch 与 XHR

只劫持 XMLHttpRequest 会漏掉现代代码里大量的 fetch。可以同时包装 window.fetch 与 XMLHttpRequest.prototype。包装 fetch 时不要假设调用方不克隆 Response 去读体，监控侧只读 status 与头即可，避免和消费方抢读同一个 body 流。

export function patchFetch(): void {
  const orig = window.fetch.bind(window);
  window.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
    const start = performance.now();
    const req = input instanceof Request ? input : new Request(input, init);
    try {
      const res = await orig(req);
      const end = performance.now();
      enqueue({
        type: "performance",
        subType: "fetch",
        url: req.url,
        method: req.method,
        status: res.status,
        duration: end - start,
        pageURL: location.href,
      });
      scheduleFlush(getConfig().reportUrl);
      return res;
    } catch (err) {
      const end = performance.now();
      enqueue({
        type: "error",
        subType: "fetch",
        url: req.url,
        method: req.method,
        duration: end - start,
        message: err instanceof Error ? err.message : String(err),
        pageURL: location.href,
      });
      scheduleFlush(getConfig().reportUrl);
      throw err;
    }
  };
}

XHR 劫持仍可用 open、send 包装，在 loadend 上打点时间戳，与上文思路一致，此处不重复贴全。

错误上报

资源错误与 JS 运行时错误要分开通道。window.addEventListener('error', …, true) 在捕获阶段能拿到 script、link、img 等加载失败，event.target 指向元素。纯 JS 语法与运行时错误同一事件里 target 往往为空，可配合 window.onerror 或同一监听里分支处理。ErrorEvent 上的 message 在跨域脚本且未正确配置 crossorigin 时可能是统一口令，需要和源站 CORS 配置一起核实。

Promise 未处理拒绝用 unhandledrejection。上报体里尽量带 reason 的栈信息，字符串化时注意大对象。

事件路径不要用已弃用的 event.path，改用 event.composedPath()。

错误从页面钻进队列前，按类型分流，便于后端路由到不同看板。

如下图所示。

资源、脚本、Promise 三类错误进入同一条上报管道前的分流意象。

function elementPath(ev: Event): string[] {
  const path = typeof ev.composedPath === "function" ? ev.composedPath() : [];
  return path
    .filter((n): n is Element => n instanceof Element)
    .map((el) => el.tagName);
}

export function initGlobalErrorHandlers(): void {
  window.addEventListener(
    "error",
    (ev) => {
      const t = ev.target;
      if (
        t &&
        t instanceof HTMLElement &&
        (t instanceof HTMLImageElement ||
          t instanceof HTMLScriptElement ||
          t instanceof HTMLLinkElement)
      ) {
        const url =
          "src" in t && t.src ? t.src : "href" in t && t.href ? t.href : "";
        enqueue({
          type: "error",
          subType: "resource",
          url,
          tag: t.tagName,
          paths: elementPath(ev),
          pageURL: location.href,
        });
        scheduleFlush(getConfig().reportUrl);
        return;
      }
      if (!ev.message) return;
      enqueue({
        type: "error",
        subType: "js",
        message: ev.message,
        filename: ev.filename,
        lineno: ev.lineno,
        colno: ev.colno,
        stack: ev.error instanceof Error ? ev.error.stack : "",
        pageURL: location.href,
      });
      scheduleFlush(getConfig().reportUrl);
    },
    true,
  );

  window.addEventListener("unhandledrejection", (ev) => {
    const reason = ev.reason;
    enqueue({
      type: "error",
      subType: "promise",
      stack: reason instanceof Error ? reason.stack : String(reason),
      pageURL: location.href,
    });
    scheduleFlush(getConfig().reportUrl);
  });
}

若担心第三方脚本堆栈污染，可在入口做采样或域名过滤。生产环境应上传 source map 到私有桶，由服务端按 release 解析栈，而不是把完整文件路径暴露给前端库。

行为数据：PV、停留时长、点击

PV 在每次路由或首屏进入时打一条，带上 document.referrer 与本地生成的会话或设备标识。UV 必须在服务端用 cookie、登录 id 或可信指纹聚合，客户端只能提供匿名 id。单页应用要在路由变化时手动调一次 reportPv，仅依赖首屏加载会严重低估。

停留时长用 visibilitychange 记录可见累计时间，比只在 beforeunload 减一次更准，尤其是后台标签与 bfcache 场景。离开页面时再发一条汇总，字段里带 visibleMs 即可。下面是一段与队列解耦的计时思路，需与上文的 enqueue、flushQueue、getConfig 同模块配合使用。

import { enqueue, flushQueue } from "./queue";
import { getConfig } from "./config";

let visibleAccum = 0;
let lastVisibleStart = performance.now();

document.addEventListener("visibilitychange", () => {
  const now = performance.now();
  if (document.visibilityState === "visible") {
    lastVisibleStart = now;
  } else {
    visibleAccum += now - lastVisibleStart;
  }
});

window.addEventListener("pagehide", () => {
  if (document.visibilityState === "visible") {
    visibleAccum += performance.now() - lastVisibleStart;
  }
  enqueue({
    type: "behavior",
    subType: "dwell",
    visibleMs: Math.round(visibleAccum),
    pageURL: location.href,
  });
  flushQueue(getConfig().reportUrl, true);
});

点击监听建议防抖，避免长按或滑动误触暴风上报。坐标与 outerHTML 体积要限长，防止队列爆炸。敏感页面不要上传完整 outerHTML，可只保留 data- 业务埋点键名。

下面用 sessionStorage 存会话 id，首次访问时用 crypto.randomUUID() 生成。若需兼容极老环境，可再降级到时间戳加长随机串。

function createSessionId(): string {
  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
    return crypto.randomUUID();
  }
  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
}

let sessionId = sessionStorage.getItem("fd_sid") ?? "";
if (!sessionId) {
  sessionId = createSessionId();
  sessionStorage.setItem("fd_sid", sessionId);
}

export function reportPv(): void {
  enqueue({
    type: "behavior",
    subType: "pv",
    pageURL: location.href,
    referrer: document.referrer,
    sessionId,
  });
  scheduleFlush(getConfig().reportUrl);
}

export function reportClickDebounced(delayMs = 500): void {
  let timer: ReturnType<typeof setTimeout> | null = null;
  window.addEventListener("pointerdown", (ev) => {
    if (!(ev.target instanceof Element)) return;
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      timer = null;
      const el = ev.target;
      const r = el.getBoundingClientRect();
      enqueue({
        type: "behavior",
        subType: "click",
        tag: el.tagName,
        x: r.left,
        y: r.top,
        paths: elementPath(ev),
        pageURL: location.href,
        sessionId,
      });
      scheduleFlush(getConfig().reportUrl);
    }, delayMs);
  });
}

上线前建议核对的一张表

把下面几项当成发布前 checklist，在 Chrome 与一种目标内核（如 Safari 或内置浏览器）各测一遍。

核对项	怎么核实	常见坑
sendBeacon 是否到达	Network 里看 report 请求体与状态码	跨域未放行 POST、413 体积过大
LCP 是否合理	Lighthouse 与 SDK 数值同页对比	iframe、影子根、元素已移除
资源耗时是否全 0	挑一条 CDN 资源看 responseStart	缺 Timing-Allow-Origin
软导航 PV	手动点路由后看是否产生新 pv 事件	只监听了首次 load
重复 flush	快速切换标签看上报条数是否翻倍	visibility 与 pagehide 未去重

小结

把上报做成"队列加空闲 flush 加离开兜底"，用 sendBeacon 携带 JSON Blob，性能侧用 PerformanceObserver 与 PerformanceNavigationTiming 对齐现代指标，并补上 CLS、INP 的采集意识，错误侧区分资源与脚本并改用 composedPath，行为侧把 PV、软导航与可见停留时间说清楚，就是一个可演进的最小监控采集层。存储与查询、告警与大盘属于下一篇文章。