React Router PrefetchPageLinks 组件详解：预取目标页面资源实现即时导航

PrefetchPageLinks 是 React Router 框架模式（Framework Mode）下的 SSR 组件，它为目标页面渲染 <link rel="prefetch|modulepreload"> 标签，提前拉取该页面的 JS 模块与数据，使用户点击后能“即时”到达目标页。本文基于官方 API 文档与 packages/react-router 源码实现，完整覆盖组件签名、Props 说明、典型使用场景（如搜索框输入时预取结果页），并深入解析其内部如何匹配路由、计算数据预取 URL 与去重资源链接，帮助你在实际项目中正确且高效地应用页面级预取。

组件概述与定位

PrefetchPageLinks 的官方文档见 docs/api/components/PrefetchPageLinks.md，该文档标注 [MODES: framework]，即仅在框架模式下可用。其核心能力可以概括为两点：

• 为目标页面渲染 <link rel=prefetch|modulepreload> 标签（参考 中的 JSDoc 说明），覆盖 JS 模块（modulepreload）与 数据请求（rel="prefetch" as="fetch"）两类资源；
• 它是 <Link prefetch> 的底层实现。<Link> 的 prefetch 属性 在内部正是复用该组件，但你可以出于任意其他目的直接渲染它。

文档给出的典型场景是：当用户在搜索框中输入时渲染该组件，先于用户点击把搜索结果页预取好。官方示例（继承自 API 文档）：

import { PrefetchPageLinks } from "react-router";

<PrefetchPageLinks page="/absolute/path" />

组件签名与 Props

函数签名

function PrefetchPageLinks({ page, ...linkProps }: PageLinkDescriptor)

该签名来自源码 PrefetchPageLinks 入口：组件接收 PageLinkDescriptor 类型的 props，解构出 page，其余部分作为 linkProps 透传给最终的 <link> 标签。

Props 说明

Prop	类型	说明
page	string	要预取页面的绝对路径，例如 /absolute/path
linkProps	HTMLLinkElement 其余属性	展开（spread）到 <link> 标签上的额外属性，如 crossOrigin、integrity、rel 等

从源码看，除显式 Props 外还有一个隐式行为：组件会读取 FrameworkContext 中的 nonce，若你没有显式传入 nonce，会自动补上（components.tsx#L368-L370），这对 CSP 严格环境下正确注入 <link> 标签很重要。

内部实现原理（源码解析）

1. 路由匹配：决定预取哪些匹配项

组件入口首先用 matchRoutes 把 page 路径映射到路由树上：

let matches = React.useMemo(
  () => matchRoutes(router.routes, page, router.basename),
  [router.routes, page, router.basename],
);

if (!matches) {
  return null; // 路径不匹配任何路由则不渲染任何标签
}

见 components.tsx#L359-L366。这意味着 page 必须是一个能通过当前路由表匹配的绝对路径；若不匹配，组件返回 null，不会报错也不会渲染任何标签。

2. 非 RSC 路径：三类 <link> 标签

非 RSC 场景下组件委托给 PrefetchPageLinksImpl（components.tsx#L450-L575），最终输出三类标签：

{/* 1) 数据预取 */}
{dataHrefs.map((href) => (
  <link key={href} rel="prefetch" as="fetch" href={href} {...linkProps} />
))}
{/* 2) 模块预加载 */}
{moduleHrefs.map((href) => (
  <link key={href} rel="modulepreload" href={href} {...linkProps} />
))}
{/* 3) 路由模块 links 导出的资源（样式/预加载） */}
{keyedPrefetchLinks.map(({ key, link }) => (
  <link key={key} nonce={linkProps.nonce} {...link} ... />
))}

三类标签的来源与计算逻辑分别如下：

数据预取 URL（single fetch）。dataHrefs 通过 singleFetchUrl(page, "data") 构造单请求地址，且并行于数据策略中的请求逻辑：

• 跳过当前页：若 page 等于当前 location.pathname + search + hash，直接返回空数组。源码注释说明原因是：由于我们选择性地启用 revalidation，为当前页计算会总是触发对现有 loader 的多余预取（components.tsx#L487-L492）；
• _routes 参数收窄 loader 范围：遍历 nextMatches 时，凡存在 shouldRevalidate 自定义函数、或存在 client loader（hasClientLoader）的路由都会置 foundOptOutRoute；仅当确实有路由“退出”而仍有其他路由需要预取时，才在 URL 上追加 _routes=<route id 逗号串>，把服务端 loader 限定到“有 server loader 且未退出预取”的集合（components.tsx#L496-L533）；
• 若没有任何可预取的路由（routesParams.size === 0），同样不输出数据标签。

模块预加载 URL。moduleHrefs = getModuleLinkHrefs(newMatchesForAssets, manifest)，其中 newMatchesForAssets 由 getNewMatchesForLinks 计算——它对比“当前页匹配”与“目标页匹配”，只保留新出现的路由或路径参数发生变化的路由（如 /users/123 → /users/456、splat 段变化）。这保证了不会重复预取当前页已加载的模块。

路由 links 导出资源的预取。useKeyedPrefetchLinks 异步调用 getKeyedPrefetchLinks：加载目标路由模块后调用其 links() 导出，只保留 rel === "stylesheet" 或 rel === "preload" 的描述符，并统一改写为预取语义——样式表变为 rel="prefetch" as="style"，preload 变为 rel="prefetch"，最后经 dedupeLinkDescriptors 去重。

3. RSC 路径：仅数据预取

当处于 RSC Router 上下文（useIsRSCRouterContext() 为真）时，组件走 RSCPrefetchPageLinksImpl（components.tsx#L407-L448）：同样跳过当前页，用 singleFetchUrl(page, "rsc") 构造 URL，并对带有 shouldRevalidate 的路由追加 _routes 参数，最终仅渲染 rel="prefetch" as="fetch" 的数据标签。从源码结构看，RSC 路径不做模块级 modulepreload，资源发现依赖 RSC 流自身的机制。

与 <Link prefetch> 的关系

在 Link 实现 中可以看到，prefetch 行为触发后，Link 就是直接内嵌渲染该组件：

return shouldPrefetch && !isAbsolute ? (
  <>
    {link}
    <PrefetchPageLinks page={href} />
  </>
) : (
  link
);

shouldPrefetch 由 usePrefetchBehavior 根据 prefetch 取值（"none" | "intent" | "render" | "viewport"，定义见 components.tsx#L87-L95）决定：render 渲染即预取、intent 聚焦/悬停/触摸时预取、viewport 进入视口时预取。这解释了 <Link prefetch="render"> 与手写 <PrefetchPageLinks page="/..." /> 产出标签的一致性。

此外，<Links /> 组件在渲染路由模块导出的链接时，若遇到页面级链接描述符（isPageLinkDescriptor 为真），也会复用 PrefetchPageLinks 而非原生 <link>（components.tsx#L307-L322），从而让“路由声明式预取其他页面”也能走同一套去重与匹配逻辑。

端到端验证：集成测试

预取行为的端到端断言集中在 integration/prefetch-test.ts。测试按 prefetch="none"、prefetch="render"、prefetch="intent"（hover 与 focus 两种触发）、prefetch="viewport" 等场景，验证页面加载后网络请求中是否出现对应的 modulepreload 与数据预取请求，并覆盖带/不带 loader 的页面（/prefetch-with-loader、/prefetch-without-loader）等差异。如果你修改或复现预取逻辑，可以直接参考该测试的请求断言方式。

使用建议与适用边界

• 仅框架模式可用：文档标注 [MODES: framework]，组件依赖 FrameworkContext（manifest、routeModules、nonce）与 DataRouterContext，即需要渲染在 <HydratedRouter>/数据路由体系内，且必须位于 DataRouterContext.Provider 之下（否则 invariant 会抛出错误）。
• page 必须是可匹配的绝对路径：不匹配时组件静默返回 null；参数化路径（如 /users/456）也支持，参数变化会触发模块重新预取（见 matchPathChanged 逻辑）。
• 不要用它预取当前页：源码显式跳过当前页的数据预取，因为按当前 revalidation 语义这是无意义的重复请求。
• linkProps 的取舍：nonce 会被自动补全，通常无需手动传入；crossOrigin、integrity 等则应遵循你的 CDN/SRI 策略传入，它们会作用于数据与模块标签。
• 与懒路由发现的配合：预取解决的是“资源提前到位”，而路由模块本身的发现行为由 discover（"render" | "none"，见 懒路由发现说明）控制，两者正交，可按需组合。

小结

PrefetchPageLinks 是 React Router 框架模式下的页面级预取原语：它通过 matchRoutes 解析目标路径，输出数据 prefetch、模块 modulepreload 以及路由 links 资源改写后的 prefetch 三类标签，并对当前页、shouldRevalidate 退出、client loader、SRI/nonce 等细节做了精细处理。理解了 components.tsx 与 links.ts 中的这套计算逻辑后，你就能在搜索框、推荐位、导航菜单等场景中，把“点击即达”的即时导航体验落到具体实现上。