发布时间：2025 年 7 月 31 日
Chrome 将从 Chrome 139 开始针对我们之前一直在实验的 Soft Navigations API 推出新的源试用。通过此源试用，网站可以与真实用户一起在自己的网站上试用该 API，以便进行实地测试并向 Chrome 团队提供反馈。
什么是软导航？
软导航是指 JavaScript 拦截导航（例如，点击链接）并更新现有网页上的内容，而不是通过加载新网页来更新地址栏中的网址（通过历史记录状态来允许软导航的后退和前进）。对于用户而言，这些看起来与常规导航相同，但就浏览器而言，网页仍然是原始网页。
为何需要软导航 API
软导航 API 是一项提议的 API，用于允许基于启发式的检测，以检测单页应用 (SPA) 网站使用的所谓“软导航”。由于软导航不会发生实际的网页导航，这意味着通常在导航时发生的某些操作需要通过 JavaScript 手动管理。借助当前的 API，可以执行某些操作，例如管理导航历史记录。不过，对于这些导航，无法执行其他操作，例如衡量核心网页指标。
Soft Navigation API 允许观察软导航。虽然发起软导航的 JavaScript（通常是 JavaScript 框架）知道何时发生导航，但其他 JavaScript 和浏览器本身并不知道。
核心网页指标和 SPA
软导航 API 的主要驱动因素之一是允许衡量 SPA 的核心网页指标。核心网页指标由浏览器（以便在 Chrome 用户体验报告等工具中显示）和实时用户监控 (RUM) JavaScript 库进行衡量。
JavaScript 框架可以衡量核心网页指标的某些方面。尤其是 Interaction to Next Paint (INP) 和 Cumulative Layout Shift (CLS)，它们基于可在任意时间范围内测量的原语（分别是 Event Timing API 和 Layout Instability API），以计算 INP 和 CLS 指标。不过，其他指标（例如 Largest Contentful Paint (LCP)）仅由浏览器根据网页导航发出，并且在互动时最终确定。
软导航 API 如何允许衡量 SPA 的核心网页指标
Soft Navigation API 的首次迭代将软导航启发式方法与 LCP 重置相结合。重置后，可以针对新的有内容绘制重新发出 LCP，从而可以针对软导航衡量此指标。
最新迭代版本采用了不同的方法，将这些概念分离为软导航 API 和新的 Interaction to Contentful Paint 性能条目。interaction-contentful-paint 条目用于衡量互动后的“有内容绘制”。目前，此指标仅针对软导航发出，但如果针对所有互动启用此指标，则可实现 LCP 以外的其他潜在使用场景。
该 API 还扩展了每个 largest-contentful-paint、interaction-contentful-paint、event-timing 和 layout-shift 性能条目，以包含相应条目所针对的导航的标识符。性能条目会在其衡量的事件之后（通常是在空闲时间）发出。这意味着，在发出性能条目时，网址通常已发生更改。包含入口的导航可让您更轻松地衡量指定网址的核心网页指标，而无需将性能入口时间与软导航入口时间进行匹配。
为什么使用启发式方法？
当发生以下情况时，软导航 API 会将导航视为软导航：
- 发生基于用户的互动（不包括在没有用户互动的情况下更新网址）
- … 从而导致 DOM 修改和绘制
- … 并且发生了网址更新
- 网址更新，包括历史记录变更。
该 API 采用这种基于启发式的方法，而不是允许 JavaScript 框架“发出”软导航，或基于 Navigation API 构建，因为这样可以确保无论框架如何或开发者如何使用，都能对软导航的构成要素保持一致的理解。
即使没有用户互动或 DOM 更新（我们认为用户会将其视为导航），框架或开发者也可能会更新软导航的网址。它们还可能会在不同的时间更新网址，例如在互动开始时、仅在互动结束时（即互动完成时）或在介于两者之间的任何状态下。
与依赖框架选择不同，将软导航检测功能内置到浏览器中可建立规范的“启发式”方法（根据您在此来源试用中的反馈），从而让我们能够大规模衡量软导航的核心网页指标，并大规模比较此类衡量结果。
框架和开发者也可以忽略 Soft Navigations API 启发法，并使用底层的 Event Timing、Layout Instability 和 Interaction to Contentful Paint API 来根据需要衡量其他性能指标，但我们建议使用启发法来衡量 Core Web Vitals，以便跨网站进行衡量。
需要帮助来测试软导航 API
我们需要帮助来测试 Soft Navigations API，以测试启发式方法是否正确匹配您对何时发生软导航的预期。是否存在以下情况：您认为发生了软导航，但 API 未报告？相反，对于您认为不是软导航的重复导航，API 是否会过度报告？
我们发现，以下情况可能会导致问题：使用 replaceState 更新网址而不是添加历史记录，或者发生非用户发起的导航（例如，因超时而退出登录）。这两种情况都可以解释为不符合启发式方法，Chrome 团队认为不包含这些情况是可以接受的，但我们希望听取 Web 开发者的意见。我们尤其希望了解以下情况：启发式方法似乎已满足，但 API 仍无法识别软导航。
此外，我们还想了解此 API 和新的 Interaction to Contentful Paint 原语是否能满足主要使用场景，即允许衡量 SPA 的 Core Web Vitals。
我们希望该 API 尽可能有用，而在发布之前和网站开始依赖于实现时，更容易实现这一点。因此，我们希望 SPA 开发者以及有兴趣衡量这些网站的 Web 性能的开发者试用此 API，并告知我们其效果如何。
如何测试
您可以使用 Chrome 标志或命令行选项在本地测试该 API。此外，还可以通过源试用在现场进行测试。
如需详细了解该 API 的技术细节，尤其是如何衡量核心网页指标，请参阅我们的文档或 GitHub 代码库。此外，我们还提供 web-vitals 库的实验性软导航版本。
反馈
我们正在积极征求有关此实验的反馈意见，您可以通过以下方式提供反馈：
- 有关该 API 的反馈应以 GitHub 上的问题的形式提出。
- 如果 Chromium 实现中的 bug 尚不属于已知问题，则应在 Chrome 的问题跟踪器中提出。
- 如需提供有关网页指标的一般反馈，请发送电子邮件至 web-vitals-feedback@googlegroups.com。
如果您有疑问，也不必过于担心，我们很乐意在上述任一位置收到您的反馈，并会很乐意在上述任一位置对问题进行分诊，然后将问题重定向到正确的位置。