PerformanceObserver buffered 回放页面初始化前性能条目的处理方法

我第一次把性能观察器放到公共监控脚本里时，遇到过一个很容易误判的现象：页面已经产生了资源条目，但脚本稍晚创建的 PerformanceObserver 只收到后续数据。这个结果并不是回调失效，而是普通观察默认只关心注册后的新条目。

如果监控脚本需要补上页面初始化阶段已经进入缓冲区的某一种性能条目，应使用 observe({ type, buffered: true })。关键是 buffered 只能和单一 type 配合；它是有限缓冲的回放入口，不是无限历史数据库。

参考文档：https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe

buffered 解决的是观察器创建得太晚

PerformanceObserver 的回调会在匹配的性能条目产生后被调用。可是性能监控代码经常不是页面最早执行的脚本：它可能等配置加载完成，或者等应用壳初始化后才创建观察器。此时，资源、标记或测量条目可能已经进入对应的性能缓冲区。

buffered: true 的作用是把指定 type 当前可用的缓冲条目加入观察器自己的待交付列表。W3C 的描述强调，这些条目会在调用 observe() 后的第一次回调中交付；缓冲数量由对应指标的规范决定，并不是无限保存、持续回放所有历史。

最小写法：用 type 单独接住历史条目

下面的例子只观察资源条目。回调中的 list.getEntries() 可能先包含观察器创建前仍在缓冲区的资源条目，之后再收到新的资源条目。示例只展示处理边界，不把输出数字写死，因为条目数量取决于页面和浏览器。

// 只观察 resource，buffered 负责接住观察器创建前仍可用的历史条目
const observer = new PerformanceObserver((list, observerInstance, options) => {
  // 首次回调可能包含回放条目，后续回调承接新产生的条目
  for (const entry of list.getEntries()) {
    console.log(entry.name, entry.startTime, entry.duration);
  }

  // 丢失计数用于提醒缓冲区可能不够，不能把它当成完整历史的保证
  if (options?.droppedEntriesCount > 0) {
    console.warn("部分性能条目未进入回调缓冲");
  }
});

// buffered 必须和单一 type 一起使用
observer.observe({ type: "resource", buffered: true });

这里的“首次回调”不是一个单独的 API 开关，而是回放条目进入观察器缓冲后，由用户代理安排交付的结果。业务代码应按批次处理 list.getEntries()，不要假设回调只会有一个条目，也不要把它当成按页面完整历史排序的日志接口。

为什么不能把 buffered 写进 entryTypes

当只需要同时订阅多个类型时，可以写 entryTypes: ["mark", "measure"]；但 entryTypes 表示多类型配置，不能再和 type、buffered 或 durationThreshold 混用。需要历史回放时，应为每一种需要回放的类型分别创建单类型观察配置。

// 多类型观察适合“只订阅新条目”的场景
const liveObserver = new PerformanceObserver((list) => {
  // 统一处理 mark 和 measure，但这里没有 buffered 回放语义
  for (const entry of list.getEntries()) {
    console.log(entry.entryType, entry.name);
  }
});
liveObserver.observe({ entryTypes: ["mark", "measure"] });

// 需要回放时，拆成单一 type；不要写成 entryTypes + buffered
const markObserver = new PerformanceObserver((list) => {
  // 只处理 mark 类型，保持 buffered 的配置边界清晰
  list.getEntries().forEach((entry) => console.log(entry.name));
});
markObserver.observe({ type: "mark", buffered: true });

从规范语义看，同一个观察器还应保持一致的配置形态：始终使用 entryTypes，或始终使用 type。把两种形态交替调用可能触发 TypeError 或 InvalidModificationError，这不是把历史条目“补回来”的办法。

缓冲不是无限历史：把支持性和丢失边界写进代码

页面初始化前的条目能否被回放，取决于该条目类型是否被当前用户代理支持，以及它是否仍在对应缓冲区中。先检查 PerformanceObserver.supportedEntryTypes，可以避免把不支持的类型当作“没有数据”。

// 先判断当前环境是否认识目标 entry type
const type = "resource";
const supported = PerformanceObserver.supportedEntryTypes?.includes(type);

if (supported) {
  const observer = new PerformanceObserver((list, instance, options) => {
    // 业务侧应保存已处理条目的稳定键，避免批次重放时重复入库
    for (const entry of list.getEntries()) {
      consumeMetric(entry);
    }

    // 丢失计数出现时记录告警，但不要伪造缺失条目的内容
    if (options?.droppedEntriesCount) {
      reportLoss(options.droppedEntriesCount);
    }

    // 一次性采集完成后及时解除注册，减少不需要的开销
    instance.disconnect();
  });

  observer.observe({ type, buffered: true });
}

这段写法把三个事实分开：支持性决定能否注册，buffered 决定是否请求当前可用的历史条目，droppedEntriesCount 只提示存在丢失，不能推断丢失了哪些具体条目。若观察器需要长期运行，则不要在第一次回调里立即 disconnect()，而应按业务生命周期管理。

从旧读取方式迁移时，我会先做这张清单

如果原代码只是页面加载完成后调用 performance.getEntriesByType()，它适合一次性读取当下可见的数据；如果还要持续接收新增条目，观察器更合适。需要补接观察器创建前的条目时，再把单类型 type 与 buffered: true 放在一起。

• 先确定要观察的一个具体 type，不要从 entryTypes 直接改出 buffered。
• 把首次回调当作一批数据处理，并用业务键避免历史回放与后续采集重复入库。
• 检查 supportedEntryTypes，把不支持和没有条目区分开。
• 记录 droppedEntriesCount 这类丢失信号，不宣称 PerformanceObserver 能提供无限历史。
• 采集结束后调用 disconnect()；长期观察则把释放动作绑定到页面或组件生命周期。

我对这个能力的判断是：它很适合让稍晚启动的前端监控补上“仍在缓冲区里的初始化数据”，但不适合替代完整的历史存储。只要把 type、回放批次、支持性和丢失信号分开处理，迁移后的行为就会清楚很多。

常见问题

buffered: true 会读取页面所有历史性能条目吗？

不会。它针对指定 type 请求当前仍可用的缓冲条目，缓冲数量不是无限的，具体能力还受条目类型和用户代理实现影响。

能否在 entryTypes 中同时写多个类型再加 buffered？

不能。需要 buffered 时使用单一 type；多个类型应拆为多个单类型观察器，或接受只订阅新条目的 entryTypes 配置。

为什么回调里还要处理 droppedEntriesCount？

因为观察器缓冲可能丢失条目。这个字段提供丢失信号，帮助监控记录不完整性，但它不会恢复缺失数据。