NNext.js 中文网 GitHub

partialPrefetching

配置默认的链接预取行为,仅获取每个路由的静态部分。

partialPrefetching 在应用级别启用 Partial Prefetching。框架默认预取每个路由的静态部分;在单个链接上设置 prefetch={true} 可使用逐链接预取获取更多内容。

用法#

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig
next.config.js
module.exports = {
  cacheComponents: true,
  partialPrefetching: true,
}

partialPrefetching 需要启用 cacheComponents。否则,next dev 和 next build 会在配置校验时抛出错误。

参考#

值描述
true在整个应用中启用 Partial Prefetching。
false保留之前的预取行为,适用于在 Partial Prefetching 可用之前就已采用 Cache Components 的应用。

不设置该选项的行为等同于 false,并且在启用 cacheComponents 时会记录一条警告。这两个功能将在下一个主要版本中全面启用,届时这些选项将被移除。

预取如何解析#

在 Partial Prefetching 之前,Next.js 按可见链接进行预取:一个包含 N 个指向 N 个路由的链接的页面,会在这些链接进入视口时产生约 N 次路由预取。

使用 partialPrefetching: true 时,Next.js 改为每个路由预取一个可复用的 App Shell。App Shell 包含不依赖链接 URL 的渲染输出。特定于 URL 的内容(包括依赖 params 或 searchParams 的内容)默认在导航后解析。App Shell 会缓存在客户端,因此指向同一路由的链接会复用同一次预取。

这种模式类似于单页应用中的按路由代码分割:每个路由一个产物,由指向它的每个链接共享。

小知识:读取 cookies() 或 headers() 的路由会生成包含会话数据的 App Shell。框架会自动检测这一点,并在客户端按会话缓存该 shell。

链接可以通过 <Link prefetch={true}> 请求比 App Shell 更多的内容。该预取还会解析 params、searchParams、完整 URL 等 URL 数据及其背后的缓存内容。请参阅优化预取。

小知识:如果你使用 <Link prefetch={true}> 指向尚未启用 Partial Prefetching 的路由,开发控制台会报错,建议在全应用启用 partialPrefetching,或在该路由段上设置 prefetch = 'partial'。开发警告洞察详细介绍了每种修复方法。

按路由段覆盖#

导出了显式 prefetch 值的路由段会覆盖该路由的应用级默认值。

版本历史#

版本变更
16.3.0引入 partialPrefetching。需要启用 cacheComponents。
Next.js 中文网