前端可观测性【免费下载链接】web-vitalsEssential metrics for a healthy site.项目地址https://gitcode.com/gh_mirrors/we/web-vitals点击查看免费下载导读web-vitals是 Google Chrome 团队维护的用于测量真实用户 Web 性能指标CLS、INP、LCP、FCP、TTFB的轻量级库。本文以仓库根目录 CHANGELOG.md 为脉络主线完整梳理该库从 2020 年 v0.1 预发布到 v6.2.2 的全部版本迭代包括 v3 的 API 重构与 attribution 构建、v4 的 INP 归因深化、v5 移除 FID 并引入 LoAF 归因、v6 的 Soft Navigation 支持等关键里程碑并结合仓库源码src 目录验证各版本变更的底层实现。读完本文你将掌握 web-vitals 各版本的能力边界、破坏性变更清单、升级路径以及如何利用 attribution 构建定位性能瓶颈。一、版本全景六年演进的主线脉络web-vitals的版本史可以划分为五个明显阶段对应五大主题阶段版本区间核心主题诞生期v0.1.0 ~ v2.1.42020.04 ~ 2022.01补齐指标测量能力、CLS 定义对齐、批量上报API 重构期v3.0.0 ~ v3.5.22022.08 ~ 2024.01getXXX()→onXXX()、配置对象、attribution 构建、INP 引入归因深化期v4.0.0 ~ v4.2.42024.05 ~ 2024.10INP 分段时间、LoAF 归因、内存泄漏修复度量体系调整期v5.0.0 ~ v5.3.02025.05 ~ 2026.05移除 FID、Baseline 支持策略、LoAF 扩展归因软导航时代v6.0.0 ~ v6.2.22026.07 ~ 2026.09Soft Navigation 支持、内存与边界修复其中 v3.0.0、v4.0.0、v5.0.0、v6.0.0 四个大版本均包含破坏性变更BREAKING官方为每个大版本提供了专门的升级指南见 docs/upgrading-to-v4.md、docs/upgrading-to-v5.md、docs/upgrading-to-v6.md。二、诞生期v0.1 ~ v2.x从预发布到指标定义对齐2.1 初始发布与早期稳定化v0.1.02020-04-24首次预发布。v0.2.02020-05-03正式公开发布。此前两个补丁v0.2.1/v0.2.2确保了所有模块为纯模块pure modules、补齐 TypeScript 导出与配置并移除了 package 的type字段。v0.2.32020-06-26确保仅当 PerformanceObserver 成功创建时才上报——这是早期针对不支持 API 的浏览器的重要防御该防御逻辑至今仍保留见 src/lib/observe.ts 中的try/catch与supportedEntryTypes过滤。v0.2.42020-07-23移除unload事件监听器为后续推荐visibilitychange/pagehide埋下伏笔。2.2 v1.0.0bfcache 上报与接口定型破坏性变更v1.0.02020-11-16做了三项重要变更[BREAKING]支持在往返缓存back/forward cache恢复后上报指标bfcache 恢复被视为一次独立的页面访问所有指标会以新的 metric 对象重新上报。[BREAKING]从Metric接口中移除isFinal标志见 README.md 中的Metric接口定义。移除用于停止 LCP 观察的 scroll 监听器。这一阶段的底层机制在 src/lib/initMetric.ts 中可以看到navigationType的判定优先使用 bfcache 恢复时间getBFCacheRestoreTime() 0时标记为back-forward-cache其次才依据 Navigation Timing 条目判断prerender、restore等类型。2.3 v2.xCLS 定义对齐与批量上报v2.0.02021-06-01是 CLS 度量方式的分水岭[BREAKING]将 CLS 更新为最大会话窗口max session window5 秒、间隔上限gap1 秒的算法对应 src/onCLS.ts 与 src/lib/LayoutShiftManager.ts 的实现。确保仅在页面可见时上报 CLS。仅在 FCP 已上报时才上报 CLS对齐官方指标口径。更新唯一 ID 的版本前缀。v2.1.02021-07-01引入批量上报支持由于各指标并非同时就绪官方建议维护一个队列、在页面进入后台或卸载时统一 flush并推荐使用navigator.sendBeacon()。该模式在 README.md 中有完整示例。v2.1.x 阶段还处理了一系列兼容性问题为 Opera mini 极限省流模式补充特性检测v2.1.1、确保 TTFB 上报值小于当前页面时间v2.1.2、LCP 仅在首次隐藏前发生时才上报v2.1.3、防止 bfcache 恢复后重复上报 TTFBv2.1.4。三、v3.0.0API 重构元年3.1 破坏性变更函数命名与签名v3.0.02022-08-24是使用方式变化最大的一次发布[BREAKING]将getXXX()系列函数全部改名为onXXX()如getCLS()→onCLS()语义从获取当前值变为持续监听并上报与指标可能多次上报的行为一致。[BREAKING]为所有指标函数增加配置对象参数opts默认值为{}即onCLS(callback, opts?)的形式。[BREAKING]将ReportHandler类型更名为ReportCallback并保留别名以向后兼容。[BREAKING]支持 bfcache 恢复后上报 TTFBv2.1.4 时禁止v3 改为支持因为 bfcache 恢复被视为新的页面访问。[BREAKING]metric 的entries数组只保留最后一个LCP 条目。更新 metric ID 前缀v3 专用并将 Navigation Timing polyfill 移入 basepolyfill 构建。3.2 新能力attribution 构建、INP 与 ratingv3.0.0 同时引入了三个影响深远的新特性attribution 构建dist 中的web-vitals.attribution.*系列产物每个指标回调除Metric外额外携带attribution对象用于定位真实用户场景下的性能瓶颈根因。包内同时提供 attribution.js / attribution.d.ts 作为入口。INPInteraction to Next Paint指标支持作为当时的新兴 Core Web Vitals 指标进入库内见 src/onINP.ts。rating属性与MetricRatingThresholds每个上报的 metric 自带good | needs-improvement | poor评级阈值以[number, number]二元组形式导出见 src/index.ts 中的CLSThresholds、INPThresholds、LCPThresholds等常量例如INPThresholds [200, 500]。[!NOTE] 从 CHANGELOG 看v3.2.0 的版本号被跳过Version number skipped因此实际发布序列是 v3.1.x → v3.3.x。3.3 v3.1 ~ v3.5稳定性与细节打磨这一阶段的小版本集中在行为对齐与健壮性v3.1.0新增restore导航类型浏览器 discard 后由用户恢复reportAllChanges时上报初始 CLS 值所有 observer 延迟到页面激活activation后再创建忽略responseStart为 0 的 TTFB延迟执行 observer 回调。v3.1.1CLS 逻辑延迟到onFCP()回调之后执行。v3.3.0在 attribution 构建中也导出评级阈值裁剪 classname 选择器防止隐藏的 prerender 页面上报 LCP文档补充 Server Timing 信息。v3.3.2修复 attribution 类型安全访问 navigation entry 类型。v3.4.0bindReporter泛型化见 src/lib/bindReporter.ts其中getRating()依据阈值二元组判定good/needs-improvement/poor修复 SVG 元素的选择器生成。v3.5.0onLCP回调在独立任务中运行修复durationThreshold设为 0 时的 INP 缺陷防止不支持 INP 的浏览器把 FID 条目当作 INP 上报。v3.5.2INP 归因选择第一个非空target。四、v4.0.0归因能力深化4.1 破坏性变更类型与字段命名规范化v4.0.02024-05-13的破坏性变更集中在类型系统与归因字段命名[BREAKING]类型升级为更通用的用法支持import type显式导入。[BREAKING]拆分waitingDuration使重定向延迟更易理解TTFB 归因中waitingDuration表示从用户发起加载到页面开始处理请求的总时长重定向会显著拉大该值。[BREAKING]TTFBAttribution字段从*Time统一更名为*Duration如cacheDuration、dnsDuration、connectionDuration、requestDuration。[BREAKING]LCP 归因中resourceLoadTime更名为resourceLoadDuration。[BREAKING]新增 INP 分段时间breakdown timings与LoAFLong Animation Frame归因。[BREAKING]弃用onFID()并移除此前已弃用的 API。4.2 归因对象细化INP 三段式拆解v4 之后 INP 归因将一次交互拆解为三段可诊断的时间分量对应 README.md 中的INPAttributioninputDelay用户交互到浏览器开始处理事件监听器之间的延迟主线程忙碌导致。processingDuration首个事件监听器开始运行到全部事件监听器处理完毕的时长。presentationDelay事件处理结束到下一帧呈现在屏幕上的时长含主线程的 rAF/ResizeObserver 回调与样式布局计算以及合成器/GPU/栅格化等主线程外工作。从 src/onINP.ts 的实现看INP 值通过InteractionManager._estimateP98LongestInteraction()取交互延迟的第 98 百分位近似归因构建对应的 src/attribution/onINP.ts 在此基础之上叠加 LoAF 信息longAnimationFrameEntries、longestScript、totalScriptDuration、totalStyleAndLayoutDuration等。4.3 v4.1 ~ v4.2修复与健壮性v4.1.0将支持性检查移到onINP()函数顶部尽早返回见 src/onINP.ts 开头对PerformanceEventTiming与interactionId的守卫修复 LoAF 条目先于 event 条目派发时缺失归因的问题。v4.2.0重构 INP 归因代码以修复 Windows 10 上的错误。v4.2.1兼容 TypeScript v5.5。v4.2.2修复 bfcache 恢复后的交互计数依赖 src/lib/polyfills/interactionCountPolyfill.ts 的 polyfill 行为。v4.2.3 / v4.2.4修复 INP 归因中缺失的 LoAF 条目修复每次keydown/click都注册新事件监听器导致的内存泄漏。五、v5.0.0度量体系调整5.1 破坏性变更告别 FIDv5.0.02025-05-07标志着 Core Web Vitals 度量体系的正式切换[BREAKING]移除已弃用的onFID()函数FID 指标正式退役由 INP 全面取代。[BREAKING]浏览器支持策略切换为Baseline Widely Available所有代码使用的 JavaScript 特性均属于该基线从而保证近 30 个月内发布的主流浏览器Chrome、Firefox、Safari可直接运行。[BREAKING]对 attribution 选择器中出现的类名进行排序以降低基数cardinality减小上报数据的维度爆炸。5.2 INP 归因扩展LoAF 深入v5.0.0 将 INP 归因扩展到 LoAF 的更深层新增**最长脚本longest script摘要与脚本时长分桶buckets**信息INPLongestScriptSummary包含entry、subpartinput-delay | processing-duration | presentation-delay与intersectingDuration。支持在 attribution 构建中通过generateTarget选项自定义 target 生成函数默认使用 src/lib/getSelector.ts 生成选择器字符串自定义函数返回null/undefined时回退到默认实现。支持以不同配置多次调用onINP()——底层通过 src/lib/initUnique.ts 的WeakMap机制为每个独立配置对象创建唯一的InteractionManager实例同一配置对象重复调用则复用实例。使用visibility-state 性能条目PerformanceVisibilityState类条目以更准确地在隐藏状态下收尾指标。5.3 数值边界收敛v5.0.0 还做了一组数值钳制cap确保归因分项之和不会超过指标总值nextPaintTime钳制到processingStart。INP 分段时间合计钳制到 INP 总时长。LCP 资源加载时长钳制到 LCP 总时长。确保 idle 回调不会执行两次合并了两个相关 PR。5.4 v5.1 ~ v5.3性能与内存优化v5.1.0尽早注册visibilitychange监听LCP 仅在用户事件isTrustedtrue上最终化防止误报自定义getSelector为null/undefined时回退默认实现。v5.2.0用find()替代filter()[0]提升性能用queueMicrotask调度微任务对应 src/lib/observe.ts 中规避 Safari 回调时序问题的实现简化 event 与 LoAF 条目的清理逻辑移除过时的 FID polyfill 类型LCP 元素被移出 DOM 时回退使用LargestContentfulPaint.id修复延迟加载场景下onLCP的缺陷处理初始隐藏页面与可见性变化时注册onLCP的场景确保whenIdleOrHidden清理 idle 回调限制 pending 事件数量以节省内存新增includeProcessedEventEntries选项通过重构进一步缩小打包体积。v5.3.0移除getFirstHiddenTimePolyfill修复同一配置对象传给多个指标函数导致报错的问题为 INP 增加更健壮的interactionTarget设置。六、v6.0.0Soft Navigation 时代6.1 核心新特性软导航Soft Navigation支持v6.0.02026-07-21的旗舰特性是为支持软导航的浏览器Chromium 151提供 Core Web Vitals 的软导航上报。所谓软导航是指用户交互 → URL 变化 → 页面有新内容绘制三者同时发生时浏览器自动识别的一次导航使 SPA 无需框架接入即可被统一测量。软导航在指标语义上有以下差异详见 README.mdTTFB 在软导航后按 0 上报而非首个网络请求的时间。FCP/LCP 只统计软导航之后的首次/最大内容绘制软导航之间保留未重绘的元素不计数。INP 重置为只统计软导航之后的交互。CLS 与首页分离、重新测量。启用方式是在配置对象中传{reportSoftNavs: true}。底层实现见 src/lib/softNavs.tscheckSoftNavsEnabled()同时检查PerformanceObserver.supportedEntryTypes是否包含soft-navigation、PerformanceSoftNavigation.prototype.getLargestInteractionContentfulPaint是否为函数Firefox 存在可禁用该功能的偏好设置故需守卫且要求opts.reportSoftNavs为真。6.2 其他 v6 变更[BREAKING]通过 tsconfig 的verbatimModuleSyntax移除多余的模块导入类型改为显式import type导入见 docs/upgrading-to-v6.md。新增 source maps便于线上调试源码。将requestIdleCallback钳制为 1 秒确保即使主线程繁忙指标也能及时上报——对应 src/lib/whenIdleOrHidden.ts 中const timeout requestIdleCallback in globalThis ? 1000 : 0;的实现忙碌页面在reportAllChanges下可能因此更频繁上报。翻转includeProcessedEventEntries默认值为falsev5.2.0 引入时为 true以减小归因对象体积与内存占用。为 INP 增加bfcache 恢复后的小交互上报支持bfcache 恢复时创建新的 metric 对象见 src/onINP.ts 的onBFCacheRestore分支。6.3 v6.1 ~ v6.2收尾修复v6.1.x 与 v6.2.x 以内存与边界修复为主且每一条都可在源码中找到对应实现v6.1.0为 LCP attribution 增加Resource Timing 缓冲对应LCPAttributionReportOpts.resourceBufferSize默认 50即在前 250 条默认缓冲之外最多再缓冲 50 条资源条目用于将媒体类 LCP 归因到 URL。v6.1.1将导航交互计数作用域限定到每个 InteractionManager修复软导航场景下交互计数串号。v6.2.0防止 bfcache 恢复后误报 CLS 0 值为旧浏览器守卫supportedEntryTypes。v6.2.1修复 INP attribution 中inputDelay为负值的问题。v6.2.2限制 pending 的 LoAF 数量以防止内存泄漏——这与 src/lib/softNavs.ts 中storeSoftNavEntry只保留最近 2 条软导航条目的设计一脉相承库内所有按需暂存的数据结构都遵循有界原则。七、升级路径与实操要点7.1 大版本升级总览升级目标主要破坏性变更官方指南v3 → v4类型显式化、TTFB/LCP 归因字段更名、INP 分段时间与 LoAF 归因、onFID()弃用docs/upgrading-to-v4.mdv4 → v5onFID()移除、Baseline Widely Available、attribution 选择器类名排序docs/upgrading-to-v5.mdv5 → v6verbatimModuleSyntax显式类型导入、includeProcessedEventEntries默认值翻转docs/upgrading-to-v6.md7.2 紧跟版本的配置要点结合 CHANGELOG 与源码当前v6.x推荐的核心配置如下import {onCLS, onINP, onLCP, onTTFB, onFCP} from web-vitals; // 需要诊断根因时改用 // import {onCLS, onINP, onLCP} from web-vitals/attribution; onCLS(console.log, {reportAllChanges: false}); // INPdurationThreshold 默认 40ms见 src/onINP.ts 的 DEFAULT_DURATION_THRESHOLD onINP(console.log, { durationThreshold: 40, // v6 起默认 false仅当确需完整事件列表诊断输入延迟时开启 includeProcessedEventEntries: false, }); onLCP(console.log, { // LCP 归因中额外缓冲的 Resource Timing 条目数默认 50 resourceBufferSize: 50, }); // 软导航Chromium 151 onCLS(console.log, {reportSoftNavs: true}); onINP(console.log, {reportSoftNavs: true}); onLCP(console.log, {reportSoftNavs: true});7.3 从 CHANGELOG 中提炼的实践红线回看六年变更记录可以提炼出几条始终被维护者遵守的工程原则也是使用本库时的实践红线监听器生命周期必须闭环v0.2.4 移除 unload 监听、v4.2.4 修复每次按键/点击注册新监听器、v5.0.3 移除不再需要的 visibilitychange 监听器、v5.2.0 清理whenIdleOrHidden的 idle 回调——反复的注册/清理修复提示我们重复调用onXXX()会持续累积监听器与 PerformanceObserver应避免在同一页面反复注册README 亦有明确警告。内存有界是硬约束v5.2.0 限制 pending 事件、v6.2.2 限制 pending LoAF、softNavs 只保留最近 2 条软导航条目——说明归因数据再有用也不允许无界增长。上报时机贴近页面生命周期指标在visibilitychange到 hidden、页面卸载或 bfcache 恢复等节点收尾上报配合navigator.sendBeacon()与批量队列使用见 README.md。归因数值需要边界钳制v5.0.0 对nextPaintTime、INP breakdown、LCP load duration 的 cap 处理保证了分项之和 ≤ 总量诊断时不会出现归因数据自相矛盾。八、总结从 v0.1 的预发布到 v6.2.2web-vitals的演进路径清晰可循指标语义对齐CLS 会话窗口→ API 重构与归因构建引入v3→ INP 与 LoAF 归因深化v4/v5→ 软导航测量v6。每一个大版本都伴随明确的破坏性变更清单与升级指南小版本则持续打磨内存边界、监听器生命周期、数值钳制与浏览器兼容守卫。对于使用者而言理解这条演进主线既能安全地完成版本升级也能在阅读 CHANGELOG.md 与 src 源码时快速定位每个行为背后的设计动机。赞分享前端可观测性【免费下载链接】web-vitalsEssential metrics for a healthy site.项目地址https://gitcode.com/gh_mirrors/we/web-vitals点击查看免费下载相关推荐Cosign 版本演进全解从 v0.1 到 v3.0 的签名能力变迁与升级迁移指南Cosign 版本演进全解从 v0.1 到 v3.0 的签名能力变迁与升级迁移指南 本篇技术指南以仓库根目录的 CHANGELOG.md https://li供应链安全云原生应用安全WeasyPrint 版本演进全解读从 v0.1 到 v70.0 的安全修复、核心功能与升级迁移指南WeasyPrint 版本演进全解读从 v0.1 到 v70.0 的安全修复、核心功能与升级迁移指南 本文以仓库内 docs/changelog.rst ht文档后端Volcano 版本演进与核心能力变迁CHANGELOG v0.1 至 v0.4.2 深度解读Volcano 版本演进与核心能力变迁CHANGELOG v0.1 至 v0.4.2 深度解读 本文以仓库根目录 CHANGELOG.md https://l云原生后端任务调度批处理上一篇Nixpkgs 实战指南用 wrapFirefox 与 fetchFirefoxAddon 构建预装扩展、注入企业策略的定制 Firefox下一篇darktable 免费入门RAW 照片从发灰到出片一篇讲清创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
