前端可观测性【免费下载链接】web-vitalsEssential metrics for a healthy site.项目地址https://gitcode.com/gh_mirrors/we/web-vitals点击查看免费下载导读本文基于web-vitals仓库的官方升级文档 docs/upgrading-to-v4.md系统梳理 v3 → v4 的全部 API 变更包括「破坏性变更Breaking changes」「新特性New features」与「弃用Deprecations」三大部分并结合本仓库的 TypeScript 源码src/、类型定义src/types/与单元测试test/unit/逐项验证。读完本文你将掌握如何把基于 v3 的埋点代码平滑迁移到 v4 的 standard / attribution 双构建体系理解INP、TTFB、LCPattribution 对象中新增与重命名的字段语义以及为何onFID()需要被onINP()取代。一、版本背景v4.0.0 发布了什么web-vitals是一个约 3Kbrotli 压缩后的模块化真实用户性能指标库用于在真实用户浏览器中测量 Core Web Vitals 的记录v4.0.0 于2024-05-13发布其核心变更可概括为[BREAKING]更新类型以支持更通用的用法#471[BREAKING]拆分waitingDuration使重定向延迟更易理解#458[BREAKING]将TTFBAttribution字段从*Time重命名为*Duration#453[BREAKING]将 LCP attribution 中的resourceLoadTime重命名为resourceLoadDuration#450[BREAKING]新增 INP 细分时间与 Long Animation FrameLoAFattribution#442[BREAKING]弃用onFID()并移除此前已弃用的 API#435官方升级文档将全部变更按standard build与attribution build详见 build options两个维度归类为 ❌ 破坏性变更、 新特性、⚠️ 弃用三大类。下面逐一展开并在每处结合仓库源码给出实现层面的佐证。二、❌ 破坏性变更Breaking changes2.1 Standard build整体层面的移除standard build即不含 attribution 诊断信息的基础构建在 v4 中发生了两处整体性移除移除了 basepolyfill 构建该构建包含 FID polyfill 与 Navigation Timing polyfill用于支持旧版 Safari 浏览器#435。v4 起不再分发这一组合构建。移除了所有在 v3 中已弃用的getXXX()函数#435例如 v3 时代遗留下来的getCLS()、getFCP()、getFID()、getLCP()、getTTFB()等旧式一次性取值函数v4 中彻底删除全部统一为onXXX()订阅式回调 API。迁移提示若你此前依赖 basepolyfill 构建来兼容旧版 Safariv4 之后需要自行评估目标浏览器范围或改用 README.md 中描述的当前浏览器支持策略当前web-vitals代码使用的所有 JavaScript 特性均属于 Baseline Widely Available近 30 个月内发布的 Chrome、Firefox、Safari 均可运行但 CLS 与软导航指标仍仅限 Chromium。2.2INPMetricentries语义收紧在 standard build 中INPMetric.entries的行为发生了变化变更前v3entries包含所有interactionId匹配的 event entries其中可能混入对 INP 得分没有影响的条目。变更后v4entries只包含在同一动画帧内处理、且interactionId匹配的条目#442。这一改动在 src/attribution/onINP.ts 的groupEntriesByRenderTime()中有清晰实现库将 event entries 按renderTime即startTime duration分帧归组若某条目与已存在分组的时间差不超过 8msMath.abs(renderTime - potentialGroup.renderTime) 8则认为属于同一帧并归入该组同时只把带有interactionId的条目登记进entryToEntriesGroupMapsrc/attribution/onINP.ts。最终上报给回调的entries就是与 INP 候选交互同帧的、真正影响 INP 得分的条目集合。2.3 Attribution build三个 metric 的字段重命名与移除INPAttributionINP 归因对象经历了本轮升级中最大的一次字段重构#442v3 字段v4 字段说明eventTargetinteractionTarget用户首次交互的 DOM 元素的选择器eventTimeinteractionTime用户首次交互的发生时间eventTypeinteractionType交互类型v4 起只会是pointer或keyboardeventEntryprocessedEventEntries数组被移除改由新的processedEventEntries数组替代其中interactionType的取值逻辑可以在 src/attribution/onINP.ts 中直接看到interactionType: firstEntry.name.startsWith(key) ? keyboard : pointer,即对pointerdown、pointerup、click事件记为pointer对keydown、keyup事件记为keyboard。类型定义见 src/types/inp.ts。LCPAttributionresourceLoadTime→resourceLoadDuration#450LCP 归因对象中用于描述 LCP 资源加载耗时的字段统一改名为resourceLoadDuration与 v4 引入的「*Duration」命名风格保持一致。对应实现见 src/attribution/onLCP.ts 与 src/types/lcp.ts。TTFBAttributionTTFB 归因对象中的 4 个*Time字段全部重命名为*Duration#453并且waitingDuration进一步被拆分v3 字段v4 字段说明waitingTimewaitingDuration从用户发起加载到页面开始处理请求的总时长通常由 HTTP 重定向主导—cacheDuration新增其中用于检查 HTTP 缓存匹配所花费的时间#458dnsTimednsDurationDNS 解析耗时connectionTimeconnectionDuration建立连接耗时requestTimerequestDuration从请求发出到收到响应首字节的耗时含网络与服务器处理对应类型定义见 src/types/ttfb.ts计算逻辑见 src/attribution/onTTFB.ts库用workerStart/fetchStart与activationStart之差作为waitingDuration的结束点waitEnd从而把 service worker 启动时间也计入cacheDurationcacheDuration dnsStart - waitEnddnsDuration connectStart - dnsStartconnectionDuration connectEnd - connectStartrequestDuration metric.value - connectEnd。三、 新特性New featuresv4 在 standard build 中没有引入新特性仅有上述破坏性变更所有新能力都集中在attribution build。3.1INPAttribution新增的 INP 细分字段这是 v4 最重磅的升级点#442INP attribution 对象新增了一整套将 INP 时长拆解为输入延迟、处理耗时、呈现延迟三个子段的诊断字段用于精确定位交互卡顿的根源。新增字段语义源码位置nextPaintTime交互之后下一次绘制paint的时间戳通常等于 event timing 条目的startTime duration但由于浏览器会将时长四舍五入到最近 8ms该值会被钳制以保证不早于处理完成时间src/types/inp.tsinputDelay用户交互发生到浏览器开始运行该交互的事件监听器之间的时间主线程被其他任务占用越久该值越大src/types/inp.tsprocessingDuration从第一个事件监听器开始运行到所有事件监听器处理完毕的耗时src/types/inp.tspresentationDelay浏览器处理完所有事件监听器之后到下一帧呈现在屏幕上被用户看到的耗时包含主线程工作如requestAnimationFrame回调、ResizeObserver/IntersectionObserver回调、样式与布局计算以及主线程外的工作合成器、GPU、栅格化src/types/inp.tsprocessedEventEntries与 INP 候选交互在同一动画帧内处理的所有event条目数组可能很大默认仅在includeProcessedEventEntries: true时填充以节省内存src/types/inp.tslongAnimationFrameEntries与 INP 候选交互时间区间相交的long-animation-frameLoAF条目浏览器不支持 LoAF API 或无相交条目时为空数组src/types/inp.tsinteractionTargetElementINP 交互对应的目标元素#479 之后的迭代中并入interactionTarget这三段细分的核心关系是INP 时长 ≈ inputDelay processingDuration presentationDelay在 src/attribution/onINP.ts 中可看到三者的精确推导inputDelay: processingStart - firstEntry.startTime, processingDuration: processingEnd - processingStart, presentationDelay: nextPaintTime - processingEnd,其中processingStart被钳制为「该帧内所有事件的最早处理起点」与「交互条目自身startTime」的较大值避免inputDelay出现负数src/attribution/onINP.tsnextPaintTime被钳制为不早于处理起点processingEnd被钳制为不晚于nextPaintTime防止同步模态框如alert()导致处理耗时被错误报告为超过 INP 总时长。在此基础上attributeLoAFDetails()src/attribution/onINP.ts还会基于相交的 LoAF 条目继续拆解出longestScript、totalScriptDuration、totalStyleAndLayoutDuration、totalPaintDuration、totalUnattributedDuration等更细粒度的归因字段这些字段在 v6 中进一步扩展类型定义见 src/types/inp.ts。配套测试仓库 test/unit/attribution-onINP-test.js 专门验证了 INP attribution 各子段的计算例如「同一帧内非交互事件先开始处理时inputDelay永不为负」的场景test/unit/attribution-onINP-test.js与上述钳制逻辑一一对应。3.2TTFBAttribution新增cacheDuration在重命名的基础上v4 将原waitingDuration中「检查 HTTP 缓存」的部分独立为新字段cacheDuration#458。它标记了页面导航中总花费在检查 HTTP 缓存匹配上的时间对于由 service worker 处理的导航该时长通常还包括 service worker 的启动时间以及处理fetch事件监听器的时间存在少量跨浏览器差异。类型定义见 src/types/ttfb.ts。四、⚠️ 弃用Deprecationsv4 同时宣布了两项面向未来版本的弃用均同时影响 standard 与 attribution 两种构建onFID()函数被弃用#435由于 FID 仅度量「输入延迟」而无法反映完整交互体验业界已用INPInteraction to Next Paint取代 FID 成为 Core Web Vitals 之一。开发者应改用onINP()。事实上在 v4 及更高版本中onINP()通过 InteractionManager 持续监听交互并按 P98 估算最长交互延迟src/lib/InteractionManager.ts能覆盖 FID 无法度量的处理与呈现阶段。ReportCallback类型被弃用#483v4.0.1 起统一的ReportCallback类型被弃用取而代之的是每个指标函数各自的显式回调类型例如CLSMetric、INPMetric、LCPMetric等。这使得回调参数类型更加精确、便于 TypeScript 推导。当前各指标专属类型定义见 src/types/ 目录下的cls.ts、fcp.ts、inp.ts、lcp.ts、ttfb.ts。⚠️ 时间线所有被弃用的 API 将在下一个大版本中彻底移除。升级时若仍在使用onFID()或ReportCallback应尽快迁移避免未来 major 版本升级时出现编译错误。五、迁移实操如何把 v3 代码升级到 v45.1 包安装与构建选择v4 包的结构与 v3 基本一致继续从 npm 安装npm install web-vitals当前仓库 package.json 的exports字段列出了 v4 时代全部可用的导入入口包括web-vitalsstandard buildES module 默认入口UMD 走requireweb-vitals/attributionattribution build单指标子路径web-vitals/onCLS.js、web-vitals/onFCP.js、web-vitals/onINP.js、web-vitals/onLCP.js、web-vitals/onTTFB.js以及对应的web-vitals/attribution/onXXX.js两套构建的使用方式// standard build import {onCLS, onINP, onLCP} from web-vitals; // attribution build import {onCLS, onINP, onLCP} from web-vitals/attribution;两种构建的调用签名完全一致区别仅在于 attribution build 的 metric 对象会额外携带一个attribution属性。5.2 逐项迁移对照1替换已移除的getXXX()函数- import {getCLS, getFCP, getLCP} from web-vitals; import {onCLS, onFCP, onLCP} from web-vitals; - const cls await getCLS(); // v3 一次性取值 onCLS((metric) { /* 持续回调上报 */ });2onFID()→onINP()- import {onFID} from web-vitals; - onFID(console.log); import {onINP} from web-vitals; onINP(console.log);onINP()同样支持reportAllChanges以及自定义durationThreshold默认 40ms对应库内常量DEFAULT_DURATION_THRESHOLD见 src/onINP.ts。注意first-input条目无论时长多少都会被观察以保证页面总有 INP 得分。3attribution 字段重命名如果你在 v3 中读取了 INP / LCP / TTFB 的 attribution 字段v4 后请按下表替换- metric.attribution.eventTarget - metric.attribution.eventTime - metric.attribution.eventType metric.attribution.interactionTarget metric.attribution.interactionTime metric.attribution.interactionType // 现在只会是 pointer | keyboard - metric.attribution.resourceLoadTime metric.attribution.resourceLoadDuration - metric.attribution.waitingTime - metric.attribution.dnsTime - metric.attribution.connectionTime - metric.attribution.requestTime metric.attribution.waitingDuration metric.attribution.dnsDuration metric.attribution.connectionDuration metric.attribution.requestDuration metric.attribution.cacheDuration // 新增从 waitingDuration 中拆分4利用新增的 INP 细分字段定位卡顿升级到 v4 后你可以用inputDelay、processingDuration、presentationDelay三件套快速判断 INP 差的根源import {onINP} from web-vitals/attribution; onINP(({value, attribution}) { console.log({ value, inputDelay: attribution.inputDelay, processingDuration: attribution.processingDuration, presentationDelay: attribution.presentationDelay, }); });如果inputDelay大 → 主线程在交互前被长任务阻塞processingDuration大 → 事件监听器本身执行过慢presentationDelay大 → 渲染管线样式/布局/绘制/合成过重。5适配新配置项attribution build 的onINP()新增includeProcessedEventEntries选项默认false开启后attribution.processedEventEntries会包含 INP 时长内处理过的全部event条目而不仅是带interactionId的事件密集型页面需注意内存开销。选项类型见 src/types/inp.ts。attribution build 的onLCP()新增resourceBufferSize选项默认 50用于在浏览器默认的前 250 条 Resource Timing 之外额外缓冲的条目数帮助把媒体类 LCP 归因到具体 URL 与子段见 src/attribution/onLCP.ts。attribution build 各函数支持自定义generateTarget(el)回调用于替换默认的 CSS 选择器式目标描述例如优先使用元素上的data-name属性。六、升级影响评估与注意事项API 收敛为纯回调式v4 之后所有指标都通过onXXX(callback, opts)注册callback可能在页面生命周期内被多次调用页面visibilityState变为 hidden 时总会触发一次bfcache 恢复后还会以新 metric 对象再次上报。上报逻辑应幂等或使用iddelta做去重与增量合并详见 README.md 中delta的用法。INPMetric.entries变少是正常现象不要因为 entries 数量比 v3 少而担心数据丢失——v4 只保留同帧内真正参与 INP 计算的条目这正是为了对齐浏览器对 INP 的定义。attribution 字段的可选性INPAttribution中interactionTarget、interactionTime、interactionType、nextPaintTime在事件时长低于浏览器最小上报阈值、未派发条目时可能缺失类型上均为可选属性消费端需要做空值防护参见 src/types/inp.ts 的注释。cacheDuration的跨浏览器差异当导航由 service worker 处理时各浏览器报告的cacheDuration口径不完全一致src/types/ttfb.ts 的注释即有此说明横向对比数据时应留意。版本演进v4 之后的 v5、v6 继续在 attribution 与软导航soft navigations方向演进见 docs/upgrading-to-v5.md 与 docs/upgrading-to-v6.md但 v4 引入的字段命名体系*Duration、interaction*、INP 三子段作为基石一直延续至今。当前仓库版本为 6.2.1package.jsonv4 的迁移原则在后续版本中依然适用。七、总结web-vitalsv4 是一次以「命名规范化 INP 归因深化」为核心的大版本升级standard build删除 basepolyfill 构建与历史getXXX()APIINPMetric.entries收紧到同帧匹配条目attribution buildINP 获得inputDelay/processingDuration/presentationDelay/processedEventEntries/longAnimationFrameEntries等全新诊断能力LCP 与 TTFB 的归因字段全面改为*Duration命名并新增cacheDuration弃用onFID()正式让位于onINP()ReportCallback被各指标专属回调类型取代。对生产环境埋点代码而言v4 升级主要集中在「改 import、换字段名、补空值防护」三个动作上而对想要深挖性能根因的团队v4 的 INP 三子段归因是诊断「点击后为什么卡」的最有力工具。建议在升级后结合 attribution build 与 test/unit/attribution-onINP-test.js 等测试用例核对上报字段确保数据口径符合预期。赞分享前端可观测性【免费下载链接】web-vitalsEssential metrics for a healthy site.项目地址https://gitcode.com/gh_mirrors/we/web-vitals点击查看免费下载相关推荐plotly.py v4 迁移指南从 v3 到 v4 的完整升级路线与破坏性变更详解plotly.py v4 迁移指南从 v3 到 v4 的完整升级路线与破坏性变更详解 本指南以 plotly.py 官方文档《Version 4 Migrat数据可视化数据分析lightweight-charts v3 到 v4 迁移指南破坏性变更全解析与升级实操lightweight charts v3 到 v4 迁移指南破坏性变更全解析与升级实操 本篇迁移指南以 website/docs/migrations/fr前端图表库金融科技数据可视化ActiveAdmin v3 升级 v4 完全指南Tailwind CSS v4、暗色模式与破坏性变更迁移ActiveAdmin v3 升级 v4 完全指南Tailwind CSS v4、暗色模式与破坏性变更迁移 导读 本文基于 ActiveAdmin 官方升级文后端上一篇MiniCPM-V-4.6-Thinking与其他多模态模型的对比分析解锁高效智能交互新体验下一篇LLM Attacks探索语言模型的边界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考