Long Animation Frames API不检测掉帧，而是记录执行超50ms的单帧动画回调作为卡顿预警信号；它仅捕获rAF/timeout等调度任务，不含layout/paint耗时，需页面加载后运行动画再调用performance.getEntriesByType('long-animation-frame')获取数据。
Long Animation Frames API 是什么，它能直接检测掉帧吗
Long Animation Frames API（performance.getEntriesByType('long-animation-frame')）不检测“掉帧”，而是记录那些**执行时间超过 50ms 的单帧动画回调**。浏览器认为：如果一帧 JS 逻辑干了太久，就可能挤占后续帧的处理时间，最终导致视觉上卡顿或丢帧。所以它是个“预警信号”，不是帧率计数器。
它只捕获由 requestAnimationFrame、setTimeout、setInterval、postMessage 等触发的长任务，但不包含 layout/paint/composite 阶段耗时——那些得靠 DevTools 的 Performance 面板看。
如何启用并读取 Long Animation Frames 数据
该 API 默认开启，无需手动注册。关键是要在页面加载后、动画运行一段时间再采集，否则可能为空：
- 确保页面已加载完成（比如在
window.addEventListener('load', ...)或DOMContentLoaded后启动动画） - 让动画持续运行至少 2–3 秒，给浏览器积累足够样本
- 调用
performance.getEntriesByType('long-animation-frame')查看结果
示例（粘贴到 Console 执行）：
立即学习“前端免费学习笔记（深入）”；
setTimeout(() => {
const longFrames = performance.getEntriesByType('long-animation-frame');
console.table(longFrames.map(e => ({
duration: e.duration.toFixed(1) + 'ms',
startTime: e.startTime.toFixed(1),
name: e.name || 'anonymous'
})));
}, 3000);
注意：duration 是该回调实际执行时长，单位毫秒；name 字段在 Chrome 中通常为空，Firefox 可能带函数名（依赖实现）。
为什么查不到数据？常见拦截点
即使动画明显卡顿，performance.getEntriesByType('long-animation-frame') 也可能返回空数组，原因包括：
- 浏览器未启用该特性（旧版 Safari / 某些 Android WebView 完全不支持）
- 页面刚加载完就立刻查询，还没来得及触发长帧（需等待动画运行中）
- 长耗时发生在非调度任务中，比如同步 DOM 查询（
offsetHeight）、强制重排、或XMLHttpRequest同步请求——这些不会被归为 “animation frame” 类型 - 主线程被阻塞在 microtask 队列（如大量
Promise.then连续执行），此时 rAF 回调根本没机会进队列，也就不会产生 long-animation-frame 条目
验证是否支持：在 Console 中执行 'getEntriesByType' in performance && performance.getEntriesByType('long-animation-frame') !== undefined，返回 true 才可用。
和 Performance 面板里的 “Long Tasks” 有什么区别
long-animation-frame 是 long-task 的子集，但过滤更严格：
-
long-task捕获所有 >50ms 的主线程任务（含解析 HTML、JS 编译、GC 等） -
long-animation-frame只抓那些明确属于动画调度上下文的任务（即由 rAF / setTimeout 等触发，且浏览器判定其与渲染帧强相关） - 同一个长任务，在 Performance 面板里可能显示为一条 “Long Task”，但在 API 中只会在它**恰好落在 rAF 回调内**时才计入
long-animation-frame
真正卡顿的根因往往藏在两者交集之外：比如每帧都读 getBoundingClientRect() 触发重排，这个操作本身可能不到 50ms，但会把 layout 阶段拖慢，导致后续帧来不及提交——这种问题，long-animation-frame 不报，Performance 面板的 Layout 栏才会亮红灯。
