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

原创2026-09-24 13:11:541,815 阅读
文章标签:前端可观测性

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 由浏览器自动识别,当以下三件事同时发生即被判定为一次软导航:

  1. 发生了一次用户交互;
  2. URL 发生了变化;
  3. 屏幕上发生了新的绘制(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(),需要同时满足三个条件才启用:

  1. PerformanceObserver.supportedEntryTypes 包含 'soft-navigation'(同时防御了 Firefox 用户关闭该特性偏好设置的情况);
  2. PerformanceSoftNavigation.prototype.getLargestInteractionContentfulPaint 是函数(仅支持新式方法实现,即已稳定且无旗标发布的版本);
  3. 调用方显式传入了 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 的实操清单

综合以上分析,给出可直接执行的升级步骤:

  1. 更新依赖:将 web-vitals 从 v5 升级到 v6,例如 npm install web-vitals@^6;
  2. 修复类型导入:搜索代码中对 web-vitals 类型的导入,如 Metric、INPMetric、ReportOpts 等,统一改为 import type {...} from 'web-vitals';函数与阈值常量的导入保持不变;
  3. 评估 INP attribution:若使用 web-vitals/attribution 且依赖 attribution.processedEventEntries 定位同帧事件,在 onINP() 中显式设置 includeProcessedEventEntries: true;否则保持默认即可获得更低的内存占用;
  4. 接入 Soft Navigation(可选):在需要覆盖 SPA 软导航的场景,为 onCLS/onINP/onLCP 传入 {reportSoftNavs: true},并按需注册第二套回调同时采集传统导航指标;
  5. 修正上报的页面定位:凡上报逻辑中记录页面 URL 的地方,改用 metric.navigationURL 而非 location.href;
  6. 回归验证:参考 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。

登录后查看全文
web-vitals