web-vitals v6 升级指南：破坏性变更、Soft Navigation 支持与迁移清单

前端可观测性【免费下载链接】web-vitalsEssential metrics for a healthy site.项目地址https://gitcode.com/gh_mirrors/we/web-vitals点击查看免费下载web-vitalsv6 是 Google Chrome 团队维护的真实用户性能指标采集库的一次重要版本升级其核心亮点是为 Chromium 151 引入 Core Web Vitals 的 Soft Navigation软导航独立上报能力同时收紧了两处影响 API 使用方式的默认行为。本文基于 docs/upgrading-to-v6.md 整理全部 v5 → v6 的差异并结合当前仓库源码当前版本为 6.2.1见 package.json逐条讲解改动动机、影响范围与迁移做法。读完本文你将能够识别哪些代码在升级后会编译报错或行为变化、正确启用 Soft Navigation 指标上报以及理解 attribution 构建中includeProcessedEventEntries默认值翻转背后的内存权衡。升级前必读v6 变更全景web-vitals同时发布 standard 与 attribution 两种构建构建差异详见 README.md 的 Build options 章节。v6 的变更被官方划分为三类破坏性变更Breaking changes、新特性New features与弃用项Deprecations并明确标注每条变更作用于哪种构建。以下是官方升级文档的完整清单类别构建变更点影响❌ 破坏性变更Standard类型改为显式导出可能需要使用import typeTypeScript 编译期❌ 破坏性变更StandardrequestIdleCallback被限制为 1 秒超时繁忙页面下指标上报时机❌ 破坏性变更AttributionincludeProcessedEventEntries默认值改为falseonINP()的 attribution 对象内容 新特性全部Soft Navigation 上报支持Chromium 151核心功能扩展 新特性全部发布产物附带 sourcemaps线上调试体验⚠️ 弃用项—v6 没有任何弃用项无需处理仓库的 CHANGELOG.md 在 v6.0.0 条目中与官方升级文档相互印证逐条列明了相同的破坏性变更与新特性可作为升级后的回归核对清单。破坏性变更详解v6 的破坏性变更共有三处其中两处属于 standard 构建的通用改动一处属于 attribution 构建的onINP()专属改动。标准构建一类型改为显式导出需使用import type变更内容v6 起web-vitals的类型以显式类型形式导出如果你在代码中显式导入这些类型可能需要改为import type语法例如import type {Metric} from web-vitals;注意此变更不涉及onLCP之类的函数导出函数仍按原方式导入。换句话说只有纯类型如Metric、INPMetric、ReportOpts等受此影响运行时值指标函数与阈值常量不受影响。底层原因从源码看src/index.ts 通过export * from ./types.js转发所有类型定义而各指标函数如 src/onINP.ts则是独立的运行时导出。v6 结合 TypeScript 的verbatimModuleSyntax见 tsconfig.json移除冗余模块要求使用方显式区分类型导入与值导入。如果你的项目开启了严格的类型检查升级后出现 cannot be used as a value 一类报错时将对应导入改为import type即可。标准构建二requestIdleCallback 上限 1 秒繁忙页面也能上报变更内容v6 将内部requestIdleCallback的超时上限timeout固定为 1 秒确保即使主线程长期繁忙指标也能在可预期的时间内上报。影响对于极繁忙的页面配合reportAllChanges选项时指标可能比 v5 更频繁地触发上报——v5 在页面持续忙碌时可能一直等待空闲而迟迟不报。实现验证这一改动直接体现在 src/lib/whenIdleOrHidden.ts 中源码注释明确引用了 issue #754// Cap the requestIdleCallback to 1 sec for very busy apps // https://github.com/GoogleChrome/web-vitals/issues/754 // If not using rIC, then the setTimeout timeout should be 0 const timeout requestIdleCallback in globalThis ? 1000 : 0;该工具函数被 CLS、INP 等多个指标的实现共用例如 src/onINP.ts 在处理事件条目时通过whenIdleOrHidden排队因此这一上限对全库生效不支持requestIdleCallback的环境退化为setTimeout(0)支持的环境则保证回调最迟 1 秒内执行。迁移建议如果此前依赖页面空闲后才上报的时序做数据处理升级后需要注意回调可能提前触发一般情况下无需改动代码此变更只会让指标上报更及时。Attribution 构建includeProcessedEventEntries默认值翻转为false变更内容attribution 构建中onINP()的includeProcessedEventEntries选项默认值由true改为false。如果你仍希望在 INP 的 attribution 对象中拿到同一动画帧内处理过的全部event条目必须显式设置import {onINP} from web-vitals/attribution; onINP(callback, {includeProcessedEventEntries: true});设计动机processedEventEntries可能包含大量事件条目在交互密集、事件频繁的页面上会显著增大内存占用与 attribution 对象体积而这一能力对大多数用户而言使用频率很低。v6 将其默认关闭换取默认场景下更小的内存开销。源码佐证在 src/attribution/onINP.ts 中groupEntriesByRenderTime()收集条目时明确检查该选项// processedEventEntries can be quite large, so only include them if // the user explicitly requests them (default is to include). if (opts.includeProcessedEventEntries) { group.entries.push(entry); }同文件构造 attribution 对象时src/attribution/onINP.tsprocessedEventEntries字段取自该分组默认情况下分组内为空数组INPAttribution.processedEventEntries即为[]。需要特别说明的配套行为无论该选项取值如何指标对象上的entries字段始终包含带interactionId的事件条目即与 INP 计算直接相关的条目。includeProcessedEventEntries只决定 attribution 中是否额外包含不带interactionId的同帧事件。因此你只需要定位 INP 主交互 → 保持默认false内存最优你需要深挖同一帧内还有哪些事件挤占了主线程 → 显式开启true。从仓库 CHANGELOGv6.0.0 条目看该默认值翻转与 Soft Navigation 支持同批发布CHANGELOG.md升级时建议一并评估。新特性一Soft Navigation 的 Core Web Vitals 上报v6 最重磅的新特性是在支持 Soft Navigations 与 Interaction Contentful Paint 性能条目的浏览器中撰写本文时对应 Chromium 151web-vitals可以为软导航单独上报 Core Web Vitals 指标。什么是 Soft Navigation传统上Core Web Vitals 只针对整页导航hard navigation统计。而大量 Single Page ApplicationSPA通过软导航更新 URL 与历史记录——不触发浏览器完整的导航流程。Soft Navigation 由浏览器自动识别当以下三件事同时发生即被判定为一次软导航发生了一次用户交互URL 发生了变化屏幕上发生了新的绘制paint。由浏览器而非 SPA 框架来定义软导航好处是既有应用无需改动即可被测量且跨框架表现一致。当然这个定义也可能产生误报用户并不认为是导航或漏报用户认为是导航但条件不满足。软导航下的指标语义变化启用软导航上报后各指标在软导航语境下有明确的语义约定来自官方说明与 README.md 一致TTFB软导航后固定上报为0而非首次网络请求的时间FCP / LCP分别对应软导航后的首次、最大内容绘制软导航间保留未重绘的元素不计入因此软导航与硬导航测得的性能可能有差异INP重置只统计软导航之后的交互CLS重置与首页分开独立测量。此外软导航上报还会改变首页首次加载的测量方式初始 URL 的指标会在第一次软导航发生时定稿。如何启用reportSoftNavs: true在onCLS、onINP、onLCP的配置对象中传入reportSoftNavs: true即可开启README 中的完整示例import {onCLS, onINP, onLCP} from web-vitals; onCLS(console.log, {reportSoftNavs: true}); onINP(console.log, {reportSoftNavs: true}); onLCP(console.log, {reportSoftNavs: true});能力探测实现并非所有浏览器都支持软导航。仓库在 src/lib/softNavs.ts 中实现了checkSoftNavsEnabled()需要同时满足三个条件才启用PerformanceObserver.supportedEntryTypes包含soft-navigation同时防御了 Firefox 用户关闭该特性偏好设置的情况PerformanceSoftNavigation.prototype.getLargestInteractionContentfulPaint是函数仅支持新式方法实现即已稳定且无旗标发布的版本调用方显式传入了reportSoftNavs: true。对应地src/types.ts 声明了InteractionContentfulPaint与PerformanceSoftNavigation两个扩展类型后者携带interactionId、navigationType、paintTime等字段为指标计算提供数据基础。注意在不支持软导航的浏览器上如非 Chromium 151 的浏览器即使传了reportSoftNavs: true上报行为也不会改变——该标志只对支持环境生效。同时采集传统与软导航指标若你的分析体系需要同时覆盖两种导航类型可以注册两套回调分别处理传统导航与软导航指标README 中的完整示例import {onCLS, onINP, onLCP} from web-vitals; onCLS(doTraditionalProcessing); onINP(doTraditionalProcessing); onLCP(doTraditionalProcessing); onCLS(doSoftNavProcessing, {reportSoftNavs: true}); onINP(doSoftNavProcessing, {reportSoftNavs: true}); onLCP(doSoftNavProcessing, {reportSoftNavs: true});上报时务必使用navigationURL软导航指标可能在上报时已经发生了新的导航因此不要假设当前 URL 就是指标所属页面。指标对象上的navigationURL属性提供了该指标实际对应的 URL上报到分析平台时应以其为准。Metric基础类型见 README.md 的 Metric 类型定义还新增了navigationId、navigationInteractionId、navigationStartTime等软导航相关字段用于区分不同导航实例。在 INP 的实现中src/onINP.ts软导航条目到来时会先更新并上报当前指标再以soft-navigation为导航类型、以软导航条目的navigationId/interactionId/name/startTime初始化新的 INP 指标——这就是各指标能按导航实例独立归因的底层机制。新特性二发布产物附带 sourcemapsv6 的另一个新特性是为所有发布产物生成 sourcemap。构建配置 rollup.config.js 中standard 与 attribution 各自的 ESM、UMD、IIFE 共 6 个 bundle 均显式开启了sourcemap: true。这意味着线上出现性能库自身报错时可以借助 sourcemap 将压缩代码映射回 TypeScript 源码如 src/attribution/onINP.ts大幅降低线上排障难度。弃用项v6 无弃用官方升级文档明确说明 v6 没有任何弃用项There were no deprecations in v6.。因此升级时无需处理任何即将移除的 API注意力只需放在上面的破坏性变更与新特性上。从 v5 升级到 v6 的实操清单综合以上分析给出可直接执行的升级步骤更新依赖将web-vitals从 v5 升级到 v6例如npm install web-vitals^6修复类型导入搜索代码中对web-vitals类型的导入如Metric、INPMetric、ReportOpts等统一改为import type {...} from web-vitals函数与阈值常量的导入保持不变评估 INP attribution若使用web-vitals/attribution且依赖attribution.processedEventEntries定位同帧事件在onINP()中显式设置includeProcessedEventEntries: true否则保持默认即可获得更低的内存占用接入 Soft Navigation可选在需要覆盖 SPA 软导航的场景为onCLS/onINP/onLCP传入{reportSoftNavs: true}并按需注册第二套回调同时采集传统导航指标修正上报的页面定位凡上报逻辑中记录页面 URL 的地方改用metric.navigationURL而非location.href回归验证参考 README.md 的 Development 章节 运行npm run build构建、npm test跑真实浏览器测试基于 webdriver.io并在 Chromium 151 上人工验证软导航指标与navigationURL是否正确。总结web-vitalsv6 是一次小而关键的升级三处破坏性变更显式类型导出、1 秒空闲回调上限、INP attribution 默认内存优化都需要开发者显式确认或小幅调整代码Soft Navigation 支持则补齐了 SPA 场景下 Core Web Vitals 测量的短板配合reportSoftNavs选项与navigationURL字段即可获得按导航实例归因的完整指标视图。升级时对照本清单逐项处理即可平稳过渡到 v6。赞分享前端可观测性【免费下载链接】web-vitalsEssential metrics for a healthy site.项目地址https://gitcode.com/gh_mirrors/we/web-vitals点击查看免费下载相关推荐MikroORM v6 升级指南从 v5 到 v6 的破坏性变更详解与迁移实操MikroORM v6 升级指南从 v5 到 v6 的破坏性变更详解与迁移实操 本篇基于 MikroORM 官方升级文档 docs/versioned_do后端Ionic Framework v8 升级指南完整破坏性变更清单与迁移实战Ionic Framework v8 升级指南完整破坏性变更清单与迁移实战 本文以 Ionic Framework 官方 Breaking Changes 档前端移动开发跨平台aiohttp 移除同步 Web Handler 支持破坏性变更解析与迁移指南aiohttp 移除同步 Web Handler 支持破坏性变更解析与迁移指南 本篇技术指南聚焦 aiohttp 的破坏性变更条目 CHANGES/3929.后端Web框架WebSocket上一篇5个步骤快速上手开源自动驾驶系统openpilot开发指南下一篇抖音下载器终极指南3步轻松下载无水印视频完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考