用 Long Animation Frames API 定位重负载 JavaScript:Modern Web Guidance `identify-heavy-scripts` 指南实战解析
用 Long Animation Frames API 定位重负载 JavaScript:Modern Web Guidance identify-heavy-scripts 指南实战解析
本指南讲解如何在**生产环境(field)**中借助 Long Animation Frames(LoAF)API 找出真正拖慢页面的脚本,而不是只依赖实验室里的 Performance 面板。文章以 Modern Web Guidance 仓库中的 identify-heavy-scripts 指南 为主线,逐段拆解其数据模型、完整示例代码、最佳实践与浏览器支持策略,并结合仓库内的 demo.html、negative-demo.html、expectations.md 与 grader.ts,说明这套写法是如何被自动校验、并可直接落地到分析上报链路上的。
为什么要在现场数据里定位重脚本
指南开篇指出了一个现实:重负载运行的 JavaScript 会同时损害页面加载性能与交互响应性。现代 Web 应用的 JS 来源远比想象中复杂:
- 应用自身代码,以及它所依赖的框架代码;
- 第三方脚本,例如聊天挂件、视频播放器;
- 后台的分析(analytics)与营销脚本——这类脚本最容易被遗忘,却常常是主要贡献者。
而定位“页面为何不响应”的根因并不容易:需要具备跑性能 trace / profile 并解读结果的专门经验;此外现场数据与实验室数据往往差别很大,实验室只能复刻真实用户场景的一小部分,对交互类问题尤其难以定位。
Long Animation Frames API 的定位就是:一个可以在生产环境使用的轻量级 API,用来识别重负载运行的 JavaScript。指南对“重负载脚本”给出了两种形态,这个定义直接决定了后面示例代码的聚合逻辑:
- 单次运行时间很长的脚本;
- 在页面生命周期内多次运行、累计耗时很高的脚本。
LoAF 的数据模型:entry 与 PerformanceScript
指南对 API 的结构说明非常精炼但完整:
- 使用
PerformanceObserver监听长动画帧; - 当一个动画帧渲染耗时超过 50ms 时,发出一个
long-animation-frame类型的 entry; - entry 中包含该长帧的持续时长,以及在帧内执行过的脚本信息;
- entry 的
scripts属性是一个PerformanceScript对象数组,每个对象描述帧内执行的一个脚本,包含sourceURL与duration等字段。
可以把它理解成两层结构:
PerformanceLongAnimationFrameTiming (entry)
├── duration // 整个长帧的耗时
└── scripts: PerformanceScriptTiming[]
├── sourceURL // 脚本资源地址(区分应用的/三方的)
├── duration // 该脚本在本次长帧中的执行耗时
├── sourceFunctionName // 函数名(仓库 demo 中使用)
└── sourceCharPosition // 字符位置,便于定位到代码行(仓库 demo 中使用)
从源码结构看,仓库对这套字段的使用是分层的:指南与 demo 只取最稳定的 sourceURL / duration / sourceFunctionName / sourceCharPosition;而相邻的 identify-inp-causes 指南 才进一步使用 invokerType、forcedStyleDuration、forcedLayoutDuration 等更细的归因字段。这种分层是刻意为之——先保证归因代码在任何支持 LoAF 的浏览器上都能成立,再逐级加细。
实现:完整示例代码与逐段解读
指南给出的实现代码可直接复制使用,下面按注释分段解释其设计意图。
1) 跨回调累积,避免数据丢失
// Accumulate all script entries across the page lifecycle so no
// data is lost between observer callbacks.
const allScripts = [];
PerformanceObserver 的回调是按批次触发的,list.getEntries() 只包含本批次新增的 entry。如果每次回调都只处理当前批次,就会得到“每批里的第一名”,而不是整个页面生命周期的第一名。因此必须先累积脚本条目。
2) 按 sourceURL 分组,把“多次短调用”还原成“总耗时长”
const observer = new PerformanceObserver(list => {
// Collect all script entries across frames to find the biggest offenders.
allScripts.push(...list.getEntries().flatMap(entry => entry.scripts));
// Group by sourceURL so you can identify which scripts contribute
// the most total time, even if each individual invocation is short.
const scriptSource = [...new Set(allScripts.map(script => script.sourceURL))];
const scriptsBySource = scriptSource.map(sourceURL => ([sourceURL,
allScripts.filter(script => script.sourceURL === sourceURL)
]));
const processedScripts = scriptsBySource.map(([sourceURL, scripts]) => ({
sourceURL,
count: scripts.length,
totalDuration: scripts.reduce((subtotal, script) => subtotal + script.duration, 0)
}));
这段代码是整份指南的核心:flatMap 把多帧的 scripts 摊平,Set 去重得到所有来源,再用 reduce 求和。产出的三元组 { sourceURL, count, totalDuration } 同时覆盖了指南定义的两种重脚本形态——count 反映“重复执行”,totalDuration 反映“累计开销”。
3) 阈值过滤 + 排序 + 输出
// Only include scripts above a certain threshold to reduce noise.
const heavyScripts = processedScripts.filter(script => {
return script.totalDuration > 100;
});
// Sort by total duration so the worst offenders appear first,
// making it easier to prioritize optimization efforts.
heavyScripts.sort((a, b) => b.totalDuration - a.totalDuration);
// Log to the console for local debugging. In production, replace
// this with a call to send the data to your analytics service.
console.table(heavyScripts);
});
totalDuration > 100 是“降噪阈值”,单位毫秒;sort 保证优化优先级一目了然;console.table 只用于本地调试,指南明确要求在替换成上报调用后才用于生产。
4) buffered: true 捕获注册之前的帧
// Use buffered: true to capture any long frames that occurred before
// this observer was registered.
observer.observe({type: 'long-animation-frame', buffered: true});
这行代码有两个容易被写错的细节,也是仓库自动化校验的重点:
- 必须用
type属性而不是历史上的entryTypes数组写法; - 必须显式传入
buffered: true,否则在观察器注册之前发生的长帧(例如首屏加载阶段的脚本风暴)会完全丢失。
仓库的 expectations.md 把这两点固化为验收规则:
- 应使用性能观察器,并传入
long-animation-frame类型与buffered: true选项; - 不要为长动画帧引入 polyfill。
仓库内的可运行示例与它揭示的一个真实陷阱
demo.html 是一个最小可复现页面:一个按钮触发 100ms 的主线程阻塞循环,同时注册观察器打印脚本归因信息。
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
console.log('Long Animation Frame observed:', entry.duration, 'ms');
// Iterate through scripts to find the specific function responsible
// Note script entries will be empty when loading this demo from a
// local file, instead of from a server.
for (const script of entry.scripts) {
console.log(`Script execution time: ${script.duration} ms`);
console.log(`Function: ${script.sourceFunctionName || '(anonymous)'}`);
console.log(`URL: ${script.sourceURL}:${script.sourceCharPosition}`);
}
}
});
observer.observe({ type: 'long-animation-frame', buffered: true });
function verySlowOperation() {
const start = performance.now();
while (performance.now() - start < 100) {
// block main thread for 100ms
}
}
这里的注释值得单独强调:用 file:// 直接打开页面时 entry.scripts 会是空数组,必须通过 HTTP 服务加载才能观察到脚本归因。这一点直接决定了排障时的第一步——先把页面跑在服务上,再判断“没数据”是浏览器不支持还是加载方式不对。
反例:negative-demo.html 展示的四种典型错误
negative-demo.html 是一个“看起来实现了监控”的错误示范,几乎踩满了该指南的每一条约束:
| 反例中的写法 | 问题 |
|---|---|
if (!window.PerformanceLongAnimationFrame) { window.PerformanceLongAnimationFrame = function() {...} } |
伪造 LoAF 构造器,属于无效 polyfill,只会污染环境;指南明确说该 API 不支持时可安全忽略 |
obs.observe({ entryTypes: ['long-animation-frame'] }) |
使用遗留的 entryTypes 数组写法,无法配合 buffered,也拿不到注册前的条目 |
xhr.open('POST', '/analytics/report', false) 在观察器回调里 同步 发送,且直接 JSON.stringify 整个 entry |
在长帧回调里做同步网络请求,会进一步阻塞主线程;同时把大量原始字段全量上报,违背“先汇总关键信息”的要求 |
setInterval(...) 每 500ms 用 setTimeout 差值轮询“卡顿” |
自己造轮子近似检测长任务,不如直接用平台的 LoAF |
这些反例在仓库中不只是文档,而是被 grader.ts 直接判定为不合格的输入。
指南在仓库中如何被自动校验
这份指南不是“写完就完”的说明文字,它属于一个可被评测的指南体系,包含 guide.md、expectations.md、grader.ts、tasks/task.md 与 demo.html 等成对文件。理解这条链路,有助于把同样的模式迁移到自己的性能治理流程中。
1) 静态规则:禁止伪造 polyfill
test('No polyfill for Long Animation Frames is included', async () => {
const code = getCombinedCode();
const polyfillPattern = /PerformanceLongAnimationFrame\s*=/;
expect(code).not.toMatch(polyfillPattern);
});
该断言与 negative-demo.html 中的 window.PerformanceLongAnimationFrame = function() {...} 精确对应:一旦代码里给这个构造器赋值,就判定失败。
2) 运行时规则:用 spy 捕获 observe() 的真实参数
grader.ts 在页面脚本执行前注入 addInitScript,包裹 PerformanceObserver.prototype.observe,把所有调用参数写入 window._observeCalls;若运行环境没有 PerformanceObserver,则提供一个最小 mock(其 supportedEntryTypes 包含 long-animation-frame)。随后四条断言分别检查:
- 调用参数是对象且包含
type属性(而非数组形式的entryTypes); - 存在
type === 'long-animation-frame'的调用; - 存在
buffered === true的调用; - 不存在任何使用
entryTypes的调用。
这种“拦截 API 参数”的校验思路很值得借鉴:性能代码的写法很难通过阅读 diff 保证正确,但通过 spy 检查真实 observe() 参数既稳定又无副作用。
3) 指南元数据与基线状态的构建期注入
指南 frontmatter 声明了所依赖的 Web 特性:
name: identify-heavy-scripts
description: Identify the scripts most responsible for long animation frames
web-feature-ids:
- long-animation-frames
该字段会被 guide-validation.ts 校验:缺失或不是数组都会报错,且每个 ID 都要通过 validateFeature() 验证。因此指南里不能随手写一个特性名。
正文中的浏览器支持段落并没有硬编码任何结论,而是写成宏:
{{ BASELINE_STATUS("long-animation-frames") }}.
构建时由 macros.ts 处理 BASELINE_STATUS:调用 getStatusMessage(featureId, bcdKey) 取特性状态,找不到就抛 MacroError;面向 DevSite 构建时则改写成 {{ macros.BaselineStatus('...') }} 交由站点渲染。状态文本本身来自 baseline.ts:'low' → “Newly available”,'high' → “Widely available”,false → “Limited availability”,并输出 Baseline since <date> 形式的发布日期。
同时,guide-validation.ts 的 validateBaselineClaims() 会扫描正文(跳过代码块与宏行),一旦发现硬编码的“某浏览器已支持/可用”式表述就报错,提示改用宏。这套机制保证了指南里的兼容性说法不会随时间腐坏——这也是本文只描述“由宏注入状态”而不给出具体日期/版本的原因。
补充一点边界信息:LoAF 中区分 style 与 layout 的计时属性在仓库里仍被登记为待上游收录的特性
tmp-long-animation-frames-style-layout(见 pending-web-features.json,对应api.PerformanceLongAnimationFrameTiming.styleDuration)。相邻指南 identify-inp-causes 正是在用它的同时,给出了回退到合并计时(forcedStyleAndLayoutDuration、totalStyleAndLayoutDuration)的方案。这说明:诊断字段可以逐步加细,但基础归因必须建立在稳定字段上。
最佳实践:从“能打印”到“能治理”
指南列出的三条 DO,实质上是从调试脚本走向生产监控的分界线:
- 优先选择 LoAF,而不是 JS Self-Profiling API 之类的替代方案——后者运行期开销更高。对本来就卡顿的页面来说,诊断工具自己再制造开销是得不偿失的。
- 只汇总关键信息——LoAF 的 entry 细节非常多,直接全量上报既浪费带宽也淹没有效信号。示例代码产出的
{ sourceURL, count, totalDuration }就是一个合理的“压缩视图”。 - 在生产环境把数据发送到分析服务——
console.table只是本地调试手段。
结合示例代码,一个可落地的上报策略通常包含:
- 节流/采样:观察器回调可能非常频繁,上报前做批量聚合或按比例采样,避免网络与主线程双重压力;
- 字段裁剪:只上报
sourceURL、count、totalDuration,必要时附加sourceFunctionName、sourceCharPosition以定位到具体逻辑; - 异步投递:绝不使用反例中的同步
XMLHttpRequest,改用异步请求或在页面卸载时投递的 beacon 类机制; - 维度对齐:把
sourceURL与构建产物/三方供应商映射起来,才能把“某个 hash 文件名很慢”翻译成“某个团队/某个 SDK 很慢”。
浏览器支持与回退策略
指南的结论非常干脆:
- 不支持该 API 的浏览器会直接忽略 LoAF,因此可以安全使用而无需回退;
- 在多数情况下,它识别出的性能问题在其它浏览器上同样存在。
这解释了为什么 expectations.md 与 grader.ts 都要专门禁止 polyfill:LoAF 属于“可选增强”型诊断能力,加 polyfill 只会引入无效代码与维护成本。与 identify-inp-causes 中 Event Timing API“不支持就无法测量 INP”的强依赖形成对比——那里需要明确说明能力边界,而这里只需要声明“可忽略”。
常见坑清单
entry.scripts为空:本地file://打开会拿不到脚本归因,需通过服务器加载(demo.html 注释已说明)。- 用了
entryTypes:拿不到buffered能力,注册前的长帧全部丢失,也是 grader 明确禁止的写法。 - 忘记
buffered: true:首屏阶段最严重的脚本风暴恰恰发生在观察器注册之前。 - 只统计单次最长脚本:会漏掉“高频短脚本”,必须按
sourceURL聚合count与totalDuration。 - 在观察器回调里做重活:同步上报、全量序列化 entry 都会放大阻塞。
- 用轮询造一个“卡顿检测器”:见反例中的
setInterval+setTimeout差值方案,精度与成本都不如原生 LoAF。
小结
identify-heavy-scripts 指南用不到百行内容完成了一件事:把“页面为什么慢”从主观感受变成可聚合、可排序、可上报的数据。它的技术骨架由四部分组成——50ms 的长帧判定、PerformanceObserver 的 type + buffered 注册方式、按 sourceURL 聚合 count 与 totalDuration 的归因模型,以及“不做 polyfill、只上报关键字段”的工程纪律。仓库则用 expectations.md、grader.ts、demo.html 与 negative-demo.html 把这套纪律变成了可执行的正反例对照,并通过 macros.ts 与 guide-validation.ts 保证兼容性描述与特性 ID 不会失真。若后续需要把归因从“哪个脚本慢”推进到“脚本里的 style 还是 layout 慢”,可继续阅读同目录下的 identify-inp-causes 指南。