基于 fetchLater() 实现全会话 Core Web Vitals 埋点:Modern Web Guidance 的 full-session-analytics 实战解析

原创2026-11-12 22:52:371,890 阅读
文章标签:前端文档AI 技能AI 评测Agent 评测人工智能RAGCLI提示工程

基于 fetchLater() 实现全会话 Core Web Vitals 埋点:Modern Web Guidance 的 full-session-analytics 实战解析

本篇围绕 Modern Web Guidance 仓库中的 full-session-analytics 任务展开,讲解如何用 web-vitals 采集 Core Web Vitals,并通过 fetchLater() 在用户离开页面时才可靠投递,从而覆盖“整段会话”而非“仅到 load 为止”的埋点。读完后你将掌握 DeferredRequestInit 各参数的含义、AbortController 的载荷刷新模式、配额与异常处理边界,以及不依赖 unload 监听器的降级 polyfill 写法。

一、任务原文与要求拆解

关联任务的完整内容位于 guides/performance/full-session-analytics/tasks/task.md,其 YAML frontmatter 指定了评测目标应用:

---
base_app: cards-app
---
- Implement Core Web Vitals monitoring on this site using the `web-vitals` JavaScript library. The page should send the Core Web Vitals data to a collection endpoint at `/path/to/analytics/endpoint`, and it should wait to send the data until the user closes the tab or navigates away, to make sure the metric values are finalized before collecting. Ensure telemetry is tracked reliably across the entire page visit without relying on legacy unload event listeners that break bfcache.

这条任务包含五个可独立验证的技术约束:

约束 具体要求 对应实现手段
采集库 必须使用 web-vitals,不自行重写 LCP/CLS/INP 计算 onLCP、onCLS、onINP 回调
投递地址 /path/to/analytics/endpoint fetchLater(ENDPOINT, ...) 第一个参数
投递时机 用户关闭标签页或导航离开时才发送,保证指标已定稿 推迟投递,不在指标回调里立刻发请求
会话覆盖 覆盖整段访问,不只到 load 指标持续更新 + 载荷反复重排
生命周期 API 不得使用遗留 unload 监听器(破坏 bfcache) 原生 fetchLater() 或基于 visibilitychange 的 polyfill

base_app: cards-app 指向仓库内的起始应用 src/harness/base-apps/cards-app/index.html。该页面会渲染 500 张带有堆叠 drop-shadow、SVG 滤镜和 mix-blend-mode 的复杂卡片(cardCount = 500,见该文件第 228 行附近的脚本),天然会产生较长的渲染任务与可观测的 LCP/INP 数据,因此适合做“全会话性能埋点”的对照实验。

需要说明的是,任务文件本身只是给评测 agent 的“单条 bullet 提示词”,它背后的完整知识在 guides/performance/full-session-analytics/guide.md 中,参考实现在 guides/performance/full-session-analytics/demo.html,可观察断言在 guides/performance/full-session-analytics/expectations.md。

二、为什么必须放弃 unload + <img> 像素

guide.md 明确指出了遗留方案的三个问题:

  1. 不可靠:在 unload 事件里创建 <img> 像素,历史上以“尤其在移动端不可靠”著称;
  2. 拖累性能:注册 unload 监听器会让页面失去 bfcache(往返缓存)资格,直接影响用户返回时的体验;
  3. 数据易丢失:浏览器随时可能中断卸载流程,请求根本发不出去。

任务原文的“without relying on legacy unload event listeners that break bfcache”正是对第 2 点的直接约束。仓库用一份反面实现把这些问题集中展示出来,见 guides/performance/full-session-analytics/negative-demo.html:

trackSession();

setInterval(trackSession, 10000);

window.addEventListener('unload', function() {
  sessionData.duration = Math.round(performance.now() / 1000);
  const img = new Image();
  img.src = ANALYTICS_ENDPOINT + '?data=' + encodeURIComponent(JSON.stringify(sessionData));
});

这段反面示例同时踩了多个坑:每 10 秒用 fetch 发一次、用 XMLHttpRequest 发一次、再 sendBeacon 发一次(重复投递);fetch 的请求体用了 ReadableStream(fetchLater() 不允许);每次往 dataPayload 追加 10 万个字符,很快撑爆配额;最后还用 unload + new Image() 补一刀。这张“错误清单”非常有价值——它恰好逐条对应 expectations.md 里禁止的 API 集合。

三、fetchLater() 的语义:把“发送”交给浏览器

guide.md 对 fetchLater() 的定位很清晰:当不需要响应、且投递时机不紧急时,它是最可靠的向服务器发送数据的方式,典型场景就是用户分析、遥测、错误追踪和 Core Web Vitals 这类性能指标。

其工作模型可以概括为三步(对应 guide.md 的 “How to implement” 小节):

  1. 调度请求:数据一就绪就调用 fetchLater(),把载荷排入队列;
  2. 按需更新载荷:用户产生新数据或状态变化时,先 abort() 掉上一次排队的请求,再用完整的最新快照重新调用 fetchLater();
  3. 交给浏览器收尾:用户导航离开或关闭标签页时,浏览器会可靠地发送你最近一次 fetchLater() 调用中的载荷。

expectations.md 把参数形态也固定下来了:第一个参数是 URL 字符串,第二个参数是可选的 DeferredRequestInit 对象。从参考实现看,实际用到的字段有 method、headers、body、signal,批处理指南里还额外用到了 activateAfter(见 guides/performance/batch-analytics-events/guide.md)。

一个关键设计约束是:你的业务代码只调用 fetchLater(),绝不要自己直接调用 fetch()、sendBeacon() 或其它 beacon API。降级逻辑全部封装在 polyfill 内部,业务侧保持单一入口。

四、参考实现逐段解读

demo.html 把 guide.md 的三步法落成了可运行代码。下面按“配置 → 会话状态 → 队列函数 → 定时刷新”的顺序拆解。

4.1 常量与载荷结构

const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';
const logElement = document.getElementById('logOutput');

const sessionData = {
  duration: 0,
  id: crypto.randomUUID(),
};

id 用 crypto.randomUUID() 生成,保证同一次页面访问的所有信标共享一个可关联的会话标识;duration 是随会话推进不断被覆盖的字段。真实业务里可以在此结构上追加 lcp、cls、inp、errors 等字段,只要注意最终序列化后的体积。

4.2 用 AbortController 实现“覆盖式更新”

let fetchLaterController = null;

function queueBeacon() {
  // Abort any pending beacons before creating a new one.
  if (fetchLaterController) {
    fetchLaterController.abort();
    logMessage('Aborted previous pending beacon.');
  }

  fetchLaterController = new AbortController();

  // Update session duration to the current page time (converted to seconds for readability).
  sessionData.duration = Math.round(performance.now() / 1000);

  try {
    fetchLater(ANALYTICS_ENDPOINT, {
      method: 'POST',
      headers: {'content-type': 'application/json'},
      body: JSON.stringify(sessionData),
      signal: fetchLaterController.signal,
    });

    logMessage(`Queued new beacon. Session duration: ${sessionData.duration}s`);
  } catch (error) {
    logMessage(`Quota error or failure queuing beacon: ${error.message}`);
  }
}

这里有三个容易写错的地方:

  • abort() 必须在新建 AbortController 之前。先取消旧请求,再创建新的控制器与信号,否则旧信标可能仍会按旧载荷投递,造成同一会话出现两份不一致的数据。
  • signal 要传进 fetchLater() 的 init。polyfill 正是通过监听 signal 的 abort 事件来取消 visibilitychange 监听和定时器;原生实现同样依赖它丢弃排队请求。
  • try/catch 不可省略。guide.md 在代码注释里用 “IMPORTANT” 强调这一点,expectations.md 也要求 QuotaExceededError、RangeError、TypeError 被妥善处理。

注意 guide.md 的示例代码里写的是 sessionData.duration = performance.now();(毫秒),而 demo.html 用 Math.round(performance.now() / 1000)(秒)并顺手做了取整,纯为日志可读性。落地时请固定一种单位并与后端约定,不要两边混用。

4.3 会话期间的刷新节奏

// Queue the initial beacon right away
queueBeacon();

// Update the session data and queue a new beacon every 10 seconds.
setInterval(queueBeacon, 10000);

demo.html 一加载就先排一次信标(保证即使用户秒退也有数据),之后每 10 秒重排一次,把不断增长的 duration 写进载荷。浏览器只会在离开时发送“最近一次”排队的请求,所以中间那些被 abort() 的请求不会产生网络流量——这一点与 negative-demo.html 每 10 秒真实发出三个请求形成鲜明对比。

五、接入 web-vitals:把指标并入同一个载荷

任务是“用 web-vitals 采集 Core Web Vitals”,因此还需要把指标回调接到上面的重排逻辑上。仓库中关于 web-vitals 的表述可参考 guides/performance/identify-inp-causes/guide.md——它把 web-vitals 描述为用于测量 Core Web Vitals 的轻量库,并提供 onINP() 等指标回调;guides/performance/interaction-paint-timing/guide.md 中也给出了同时注册 onLCP、onCLS、onINP 的用法。

结合三步法,推荐的整合方式如下:

import { onCLS, onINP, onLCP } from 'web-vitals';

const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';

const payload = {
  id: crypto.randomUUID(),
  duration: 0,
  metrics: {},   // 每次回调只覆盖对应字段,其余指标保留
  errors: [],
};

let controller = null;

function scheduleBeacon() {
  if (controller) controller.abort();
  controller = new AbortController();

  payload.duration = Math.round(performance.now() / 1000);

  try {
    fetchLater(ANALYTICS_ENDPOINT, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(payload),
      signal: controller.signal,
    });
  } catch (error) {
    // 配额或参数错误:可退化为本地日志/降低采样,切勿在此处直接 fetch
  }
}

function record(metric) {
  payload.metrics[metric.name] = {
    value: metric.value,
    rating: metric.rating,
    id: metric.id,
  };
  scheduleBeacon();   // 指标更新后立刻重排最新快照
}

onLCP(record, { reportAllChanges: true });
onCLS(record, { reportAllChanges: true });
onINP(record, { reportAllChanges: true });

// 兜底:即使某次指标回调没有触发重排,也按固定节奏刷新会话时长
setInterval(scheduleBeacon, 10000);

要点说明:

  • metric.name(如 LCP、CLS、INP)作为 metrics 的键,天然支持“只覆盖单个指标、不清空其它指标”;
  • reportAllChanges: true 让指标在页面存活期间持续上报中间值,配合“每次都重排”就实现了任务要求的“整段会话追踪”,而不是只记录首屏那一次;
  • 绝不要在 record() 里直接 fetch() 或 sendBeacon()——expectations.md 第 2 条明确只允许 fetchLater() 作为发送通道,grader.ts 也会静态扫描 fetch(ANALYTICS_ENDPOINT 与 sendBeacon(ANALYTICS_ENDPOINT。

六、配额、异常与载荷类型的三条硬边界

6.1 约 64KB / origin 的配额

guide.md 与仓库 README 都提到 fetchLater() 的载荷配额“目前约为每个 origin 64KB”。negative-demo.html 用 sessionData.dataPayload += "a".repeat(100000); 每 10 秒追加 10 万字符,正是为了演示超限。因此:

  • DO 最小化载荷,只传必要字段(数值、评级、id、短标签),不要塞完整 DOM 片段或长堆栈;
  • DO 用 try/catch 包住调用,捕获 QuotaExceededError;
  • 一旦捕获到配额错误,业务上应降级(例如丢弃低优先级字段、降低采样率),而不是改用其它发送 API 绕过限制。

6.2 异常类型

expectations.md 列出的可抛出异常是 QuotaExceededError、RangeError、TypeError。后两者通常来自非法参数,例如把 ReadableStream 当成 body。

6.3 禁止 ReadableStream 作为 body

guide.md 的 Best Practices 最后一条是 “DO NOT use a ReadableStream object for the request body, as that will error.”。negative-demo.html 中的 new ReadableStream({ start(controller) { ... } }) 就是这一条的反例;实际可用的 body 是 JSON.stringify() 出来的字符串或 Blob/ArrayBuffer 等可一次性序列化的类型。

七、降级策略:最小 fetchLater() polyfill

guide.md 的 “Browser support and fallback strategies” 一节用 {{ BASELINE_STATUS("fetchlater") }} 宏渲染实时 Baseline 状态——该宏在构建期由 src/core/macros.ts 的 BASELINE_STATUS 处理器解析,状态数据来自 src/core/baseline.ts 中的 getStatusMessage()。因此具体版本号随 web-features 与浏览器兼容数据更新而变化,请以构建产物为准,可用仓库提供的命令查询:

pnpm baselinestatus fetchlater

该命令由 src/cli/baseline-status.ts 实现,会输出 web-feature-id、Baseline 状态与各浏览器支持版本;加 --json 可得到机器可读结果。

从 expectations.md 的表述“fetchLater() polyfill 应被打包,除非项目只支持 Chromium 浏览器”可以推断:非 Chromium 环境通常需要降级路径。guide.md 给出的 polyfill 值得逐段读懂:

globalThis.fetchLater ??= function fetchLater(url, init = {}) {
  let timeoutHandle;
  let activated = false;

  function sendNow() {
    if (!(init.signal && init.signal.aborted)) {
      // Use fetch keepalive if the browser supports it or if custom fetch
      // parameters are specified (e.g. custom headers or methods).
      // Otherwise fall back to `navigator.sendBeacon()`.
      if (
        'keepalive' in Request.prototype ||
        init.method !== 'POST' ||
        init.headers
      ) {
        fetch(url, Object.assign({}, init, {keepalive: true}));
        activated = true;
      } else {
        activated = navigator.sendBeacon(url, init.body);
      }
    }
    destroy();
  }

  function destroy() {
    document.removeEventListener('visibilitychange', sendNow);
    clearTimeout(timeoutHandle);
  }

  if (document.visibilityState === 'hidden') {
    // If the beacon was created while the page is already hidden, send data
    // ASAP but wait until the next microtask to allow all sync code to run.
    queueMicrotask(sendNow);
  } else {
    document.addEventListener('visibilitychange', sendNow);

    if (typeof init.activateAfter === 'number' && init.activateAfter >= 0) {
      timeoutHandle = setTimeout(sendNow, init.activateAfter);
    }
  }

  if (init.signal) {
    init.signal.addEventListener('abort', destroy);
  }

  return {
    get activated() {
      return activated;
    },
  };
};

几个值得注意的实现细节:

  1. globalThis.fetchLater ??=:仅在原生 API 缺失时安装,绝不覆盖原生实现。grader.ts 的静态检查也接受 globalThis.fetchLater ??= 或赋值形式的检测。
  2. 发送通道的选择条件:只要 Request.prototype 支持 keepalive,或调用方指定了非 POST 方法、自定义 headers,就走 fetch(..., {keepalive: true});否则退回 navigator.sendBeacon()。原因是 sendBeacon 只能发简单 POST,无法携带自定义请求头——而本任务的参考实现带了 content-type: application/json,实际会落到 keepalive 分支。
  3. visibilityState === 'hidden' 的微任务分支:如果信标本就是在页面已隐藏时创建的,用 queueMicrotask(sendNow) 让当前同步代码先跑完再发送,既及时又不截断调用方的逻辑。
  4. activateAfter 支持:polyfill 用 setTimeout 模拟定时激活,满足批处理场景(见 guides/performance/batch-analytics-events/guide.md);本指南的示例不使用该字段,因此只依赖“离开时发送”。
  5. abort 清理:init.signal 的 abort 事件触发 destroy(),移除监听并清定时器,确保被覆盖的旧信标不会补发。
  6. activated getter:暴露“是否真的已发出”,批处理场景用它判断队列是否该重置。

行为差异只有一点,且是内部实现细节:polyfill 用 visibilitychange 判断用户离开,而原生实现依赖浏览器的卸载处理。业务代码不需要监听 visibilitychange——这正是“只调用 fetchLater()”这一约定的价值所在。

八、如何验证实现是否达标

expectations.md 的五条断言被 guides/performance/full-session-analytics/grader.ts 翻译成了 Playwright 测试。静态部分有四条:

测试 检查方式
API 调用形态正确 正则匹配 fetchLater( 调用存在
只用 fetchLater() 发光信标 禁止出现 XMLHttpRequest、new Image、fetch(ANALYTICS_ENDPOINT、sendBeacon(ANALYTICS_ENDPOINT
配额异常被捕获 匹配 try { ... fetchLater(...) ... } catch 结构
polyfill 已打包 存在 globalThis.fetchLater ??= 或等价赋值

浏览器行为部分是最关键的一条(grader.ts 第 116 行起):

test('Only a single beacon is sent, after the user leaves the page', async ({ page }) => {
  let analyticsRequests = 0;
  page.on('request', request => {
    if (request.url().includes('/analytics/endpoint')) analyticsRequests++;
  });

  // Force the usage of the polyfill for deterministic testing of the deferred logic
  await page.addInitScript(() => { /* 删除原生 fetchLater,并给 sendBeacon / fetch 打标 */ });

  await page.goto(demoUrl);

  // Assert no immediate incorrect beacons fire before leaving
  await expectNever(page, () => Boolean(window.__prematureFlush), { forMs: 300 });
  expect(analyticsRequests).toBe(0);

  // Simulate user leaving the page (visibility hidden)
  await page.evaluate(() => {
    Object.defineProperty(document, 'visibilityState', { get: () => 'hidden', configurable: true });
    document.dispatchEvent(new Event('visibilitychange'));
  });

  await expect.poll(() => analyticsRequests).toBe(1);
});

这条测试同时验证了三件事:离开前一个请求都不能发(300ms 窗口内 expectNever)、命中端点、离开后恰好一个。测试还刻意删除了原生 fetchLater,强制走 polyfill,从而让“推迟投递”的逻辑可确定性复现。这一点对你自测也很有用:如果你的实现依赖原生 API,在非 Chromium 调试环境下行为会与生产不一致,务必两条路径都过一遍。

在仓库中运行评测的常规入口(见 docs/CONTEXT.md)是:

pnpm install
pnpm setup:playwright
pnpm link --global && gd setup-completion

# 只跑评分校准,不跑完整 agent 评测
gd dev guides/performance/full-session-analytics --test-grader

九、落地检查清单

按 guide.md 的 Best Practices 与 expectations.md 整理成可直接勾选的清单:

  • [ ] 通过 globalThis 特性检测 fetchLater(),缺失时加载 polyfill(除非明确只支持 Chromium)。
  • [ ] 所有信标只经 fetchLater() 发出,代码中不出现 fetch()、sendBeacon()、XMLHttpRequest、new Image() 直发端点。
  • [ ] 每次载荷变化都先 abort() 旧请求,再用 AbortController 新建信号重排。
  • [ ] fetchLater() 调用外层包裹 try/catch,覆盖 QuotaExceededError、RangeError、TypeError。
  • [ ] 载荷尽量精简,总量远低于约 64KB / origin 的配额。
  • [ ] body 不为 ReadableStream。
  • [ ] 不注册 unload 监听器,不依赖 beforeunload 发送数据,保住 bfcache。
  • [ ] Core Web Vitals 用 web-vitals 的 onLCP/onCLS/onINP 采集,不在指标回调里立即发请求。
  • [ ] 页面加载后立即排一次信标,并设置周期性重排,避免“秒退无数据”。

十、相关文件索引

登录后查看全文
modern-web-guidance-src