PerformanceObserver buffered 怎样补采已经发生的性能条目

页面性能采集脚本如果加载得比较晚，最容易出现一种“监控正常、数据却少了一截”的故障：PerformanceObserver 只收到了创建观察器之后产生的条目，脚本加载之前已经发生的资源、布局或交互记录没有进入回调。解决这个问题的关键不是再轮询一次，而是在 observe() 中使用具体的 type 和 buffered: true，让浏览器把该类型仍保留在性能缓冲区里的历史条目一并交给观察器。

补采历史条目时使用 observer.observe({ type: "resource", buffered: true }) 这一类配置；buffered 不能和 entryTypes 同时使用，且仍要处理类型支持性、重复消费和缓冲区已丢失的情况。

为什么观察器会漏掉已经发生的条目

默认观察模式更像“从现在开始订阅”：观察器回调会接收后续新增的 PerformanceEntry，但不会自动把页面早期已经产生的记录重新发来。对于延迟加载的监控 SDK，这个时间差就会造成首屏资源或早期交互缺口。

图1：静态结构说明图，展示 buffered 如何把性能时间线中的历史条目纳入观察器边界。

buffered 只表达“把已经在对应性能缓冲区中的条目排入观察器”，不是永久保存，也不是从网络或服务器补拉数据。条目如果早已被清理、缓冲区容量已满，或者当前浏览器不支持目标类型，观察器仍然无法凭空恢复它们。

用 type 加 buffered 补采历史记录

最小写法是把单个类型放到 type，再打开 buffered。下面以资源计时为例，回调同时承担历史批次和后续批次的处理：

// 统一处理资源条目，历史批次和后续批次都走这里
function handleResourceEntries(list, observer, options) {
  for (const entry of list.getEntries()) {
    // name 与 startTime 组成示例去重键，避免重复上报同一条记录
    const key = `${entry.name}|${entry.startTime}`;
    if (seen.has(key)) continue;
    seen.add(key);

    // 这里只读取采集所需字段，不把完整对象直接序列化上报
    report({ name: entry.name, duration: entry.duration });
  }

  // 缓冲区满时可能有记录被丢弃，告警要和正常条目分开处理
  if (options?.droppedEntriesCount > 0) {
    reportWarning(`dropped=${options.droppedEntriesCount}`);
  }
}

const seen = new Set();
const observer = new PerformanceObserver(handleResourceEntries);

// buffered 只能配合单个 type 使用，先补采已有资源条目，再继续接收新条目
observer.observe({ type: "resource", buffered: true });

回调第一次收到的批次可能包含历史资源条目，之后新资源继续进入同一个观察器。代码中的 seen 不是浏览器必需配置，而是采集端的幂等保护：当业务还会调用 performance.getEntriesByType() 做兜底，或 SDK 初始化存在重入时，统一去重可以避免重复计数。

type 和 entryTypes 为什么不能混着写

observe() 的两种写法职责不同。entryTypes 适合声明一组类型，但不能与 buffered 同时使用；需要补采历史条目时，应改成一个具体的 type。不要把下面两种配置拼成一个对象：

// 错误示例：buffered 与 entryTypes 不能同时使用
observer.observe({ entryTypes: ["resource", "mark"], buffered: true });

// 可行示例：分别为每个类型建立观察边界
const resourceObserver = new PerformanceObserver(handleResourceEntries);
resourceObserver.observe({ type: "resource", buffered: true });

const markObserver = new PerformanceObserver((list) => {
  // 中文注释：mark 类型只读取名称和开始时间，避免混入资源字段
  for (const entry of list.getEntries()) {
    report({ name: entry.name, startTime: entry.startTime });
  }
});
markObserver.observe({ type: "mark", buffered: true });

不同类型的字段和缓冲策略并不完全相同。工程上先用 PerformanceObserver.supportedEntryTypes 检查能力，再决定是否注册观察器；检查失败时可以跳过该指标，而不是让整个监控初始化失败。

去重、支持性与缓冲区边界

补采方案真正容易出错的地方有三个。第一，buffered 只覆盖浏览器仍保留的历史记录，不能当作无限队列。第二，资源计时等条目可能遇到性能缓冲区容量限制，回调参数中的 droppedEntriesCount 用来提示曾有记录因缓冲区满而丢失。第三，混用观察器回调和 performance.getEntriesByType() 时，必须在业务层定义稳定的去重键。

图2：静态边界说明图，展示配置互斥、支持性检查、去重键和缓冲区丢失提示。

如果业务特别依赖资源条目的完整性，可以在资源产生前合理设置资源计时缓冲区大小，并监听缓冲区已满事件；这只是降低丢失概率，不能替代采集端的丢失告警和采样策略。也不要把“回调没有条目”直接判断成“页面没有性能事件”，还要区分类型不支持、观察器注册过晚和历史记录已经被清理。

常见问题

buffered 会不会持续回放同一批历史条目？ 通常它用于观察器建立时把已有条目排入观察器缓冲，后续仍按新增通知工作；如果代码另行读取性能时间线，仍需在采集层去重。

可以用 entryTypes 同时观察多个类型吗？ 可以声明多个类型，但这种写法不能同时使用 buffered。需要补采时，按类型拆成多个观察器或选择一个明确的 type。

为什么打开 buffered 仍然少数据？ 重点检查目标类型是否支持、历史条目是否还在对应缓冲区，以及是否出现 droppedEntriesCount。它不能恢复已经被清理或已经因容量限制丢失的条目。

小结

把观察器创建晚导致的数据缺口补回来，核心是 type + buffered: true，而不是反复轮询。随后用支持性检查、业务去重和丢失告警把“能收到数据”提升为“知道数据是否完整”。