PerformanceObserver 无法直接监听布局抖动（Layout Shift），因为 'layout-shift' 不在其合法 entryTypes 列表中，注册后会被静默忽略；尽管 Chromium 120+ 和 Safari 17.4+ 等新版本支持通过 `performance.getEntriesByType('layout-shift')` 主动获取抖动数据，但必须在 `document.readyState === 'interactive'` 之前调用，否则首屏关键抖动将永久丢失，且移动端 WebView 普遍不支持、sources 中的 DOM 节点为弱引用易导致访问异常——真正稳定可靠的方案是采用 web-vitals 库的 `onCLS` 回调，它已封装兼容性处理、防重复计数和生命周期时机控制，避免开发者踩坑于浏览器差异、GC 引用失效和上报时机错失等致命细节。

PerformanceObserver 无法捕获 Layout Shift（CLS）。它不支持监听布局抖动事件——layout-shift 不在 PerformanceObserver 支持的 entryTypes 列表中。

为什么 PerformanceObserver 拿不到 layout-shift？

Layout Shift 是 Core Web Vitals 中的指标，由浏览器内部计算并聚合，但不作为独立 performance entry 暴露给 JavaScript。目前只有 layout-shift 的“计算结果”可通过 getEntriesByType('layout-shift') 获取，但前提是：该 API 已被启用且浏览器支持（仅 Chromium 120+、Safari 17.4+ 等新版本部分支持），且必须在页面生命周期早期注册监听器，否则会漏掉首屏抖动。

更关键的是：PerformanceObserver 构造时传入的 entryTypes 数组里，'layout-shift' 不是合法值；尝试添加会导致静默忽略，不会报错，也不会触发回调。

实际能用的替代方案：使用 LayoutShift API + 手动聚合

Chrome 和新版 Safari 提供了 LayoutShift 接口，但需配合 PerformanceObserver 的变通用法：监听 'largest-contentful-paint' 或 'navigation' 后主动轮询/一次性读取，或依赖 reportCallback（如使用 web-vitals 库）。

• 直接调用 performance.getEntriesByType('layout-shift') 可拿到已发生的抖动条目，每个条目含 value（位移分数）、sources（扰动源元素）、hadRecentInput（是否发生在用户操作后）
• 必须在 document.readyState === 'interactive' 或更早时机执行，否则首屏抖动（如图片加载导致的跳动）会被丢弃
• 不能靠 observe({ entryTypes: ['layout-shift'] }) 实时监听——这行代码无效

上报时最容易踩的坑

即使你拿到了 LayoutShift 条目，直接上报也常出问题：

• sources 数组里的 node 是弱引用，可能已被 GC，访问 node.tagName 会返回 undefined；应改用 source?.element?.tagName || 'unknown'
• 同一抖动事件可能被多次归因（尤其动态插入内容时），value 是累积值，不是增量；上报前需比对上一次的 lastValue 防止重复计数
• 移动端 WebView（如微信、QQ 浏览器）普遍不支持 layout-shift entry type，上报前必须加 if ('getEntriesByType' in performance) 和 performance.getEntriesByType('layout-shift').length 双重判断
• 不要在 DOMContentLoaded 后才开始收集——此时首屏抖动早已发生；推荐在 内联脚本中立即初始化

真正稳定可用的方案，是引入 web-vitals 库的 onCLS 回调，它封装了兼容性处理和防抖逻辑；自己手撸时，最易被忽略的是“抖动可能发生在资源加载完成前”，而你根本没机会监听到。

到这里，我们也就讲完了《PerformanceObserver监测布局抖动教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！