web-vitals v6 升级指南:破坏性变更、Soft Navigation 支持与迁移清单
web-vitals v6 升级指南:破坏性变更、Soft Navigation 支持与迁移清单
web-vitals v6 是 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 type |
TypeScript 编译期 |
| ❌ 破坏性变更 | Standard | requestIdleCallback 被限制为 1 秒超时 |
繁忙页面下指标上报时机 |
| ❌ 破坏性变更 | Attribution | includeProcessedEventEntries 默认值改为 false |
onINP() 的 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.ts),processedEventEntries 字段取自该分组;默认情况下分组内为空数组,INPAttribution.processedEventEntries 即为 []。
需要特别说明的配套行为:无论该选项取值如何,指标对象上的 entries 字段始终包含带 interactionId 的事件条目(即与 INP 计算直接相关的条目)。includeProcessedEventEntries 只决定 attribution 中是否额外包含不带 interactionId 的同帧事件。因此:
- 你只需要定位 INP 主交互 → 保持默认
false,内存最优; - 你需要深挖"同一帧内还有哪些事件挤占了主线程" → 显式开启
true。
从仓库 CHANGELOG(v6.0.0 条目)看,该默认值翻转与 Soft Navigation 支持同批发布(CHANGELOG.md),升级时建议一并评估。
新特性一:Soft Navigation 的 Core Web Vitals 上报
v6 最重磅的新特性是:在支持 Soft Navigations 与 Interaction Contentful Paint 性能条目的浏览器中(撰写本文时对应 Chromium 151+),web-vitals 可以为软导航单独上报 Core Web Vitals 指标。
什么是 Soft Navigation
传统上,Core Web Vitals 只针对整页导航(hard navigation)统计。而大量 Single Page Application(SPA)通过"软导航"更新 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 指标——这就是各指标能按导航实例独立归因的底层机制。
新特性二:发布产物附带 sourcemaps
v6 的另一个新特性是为所有发布产物生成 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-vitals v6 是一次"小而关键"的升级:三处破坏性变更(显式类型导出、1 秒空闲回调上限、INP attribution 默认内存优化)都需要开发者显式确认或小幅调整代码;Soft Navigation 支持则补齐了 SPA 场景下 Core Web Vitals 测量的短板,配合 reportSoftNavs 选项与 navigationURL 字段即可获得按导航实例归因的完整指标视图。升级时对照本清单逐项处理,即可平稳过渡到 v6。