prefetch
配置路由段在客户端导航期间如何被预取。
prefetch 路由段配置控制段在客户端导航期间如何被预取。默认情况下,框架根据应用的 partialPrefetching 设置管理该策略。要按段覆盖,请将此导出设置为以下值之一。
小知识:
prefetch导出仅在启用cacheComponents时有效。- 当段是 Client Component 时不能使用
prefetch。- 有意义的可设置值为
'partial'和'force-disabled'。'auto'是默认值,等同于省略该导出;不要显式写prefetch = 'auto'。- 同时调用
prefetch()函数的page或layout需要以另一个名称导入它,例如import { prefetch as prefetchStage } from 'next/cache'。
export const prefetch = 'partial'
export default function Page() {
return <div>...</div>
}export const prefetch = 'partial'
export default function Page() {
return <div>...</div>
}选项#
'partial'#
在不启用全局 partialPrefetching 标志的情况下,让该段选择加入 Partial Prefetching。指向 prefetch = 'partial' 段的 <Link> 会加载按路由的 App Shell,而不是旧式的完整预取。请在目标段上设置此项,而不是在链接上。
对于通过 <Link prefetch={true}> 选择加入更广泛预取的链接,Next.js 使用按链接预取。服务器渲染一个解析 URL 数据(params、searchParams 和完整 URL)的新响应。在所有内容都可静态渲染的页面上,Next.js 从静态缓存提供预取。如果页面访问非静态数据,则在运行时进行预取。
当你无法一次性为整个应用启用 partialPrefetching 时,可使用此方式进行增量采用。一旦范围内的每个路由都设置了 prefetch = 'partial',就启用全局标志并移除按路由的导出。
小知识:当 Next.js 对某个段执行按链接预取时,所有下游段都包含在同一请求中。树中更深处配置为
'force-disabled'的段仍会作为响应的一部分被预取。
export const prefetch = 'partial''force-disabled'#
从不预取该段。客户端不会在导航前请求段数据。适用于预取会造成浪费的段,例如需要身份验证且很少访问的页面。
小知识:
'force-disabled'不会阻止 Next.js 预取有关该路由的 metadata。但是,该段及所有更深段的实际段数据将被排除在预取之外。
与 <Link prefetch> 属性的关系#
预取始于表达意图的 <Link>(是否应预取此目标,以及预取的积极程度),终于设置成本上限的段(对于指向此处的任何链接,可以提前做多少工作)。
目标无法知道哪些链接指向它,因此段配置限制了任何 <Link prefetch={true}> 所拉取的内容:
'partial':对于默认链接,预取 App Shell;<Link prefetch={true}>还会解析 URL 数据(params、searchParams和完整 URL)及其背后的缓存内容。'force-disabled':完全跳过段数据。
<Link prefetch={false}> 无论目标如何配置,都会在链接级别跳过预取。
小知识:在所有内容都可静态渲染的页面上,Next.js 从静态缓存(或 CDN)提供预取。如果页面访问 cookies 或 headers 等非静态数据,则会在运行时通过新的服务器渲染进行预取,这会在每次页面浏览时消耗服务器 CPU。
TypeScript#
type Prefetch = 'auto' | 'partial' | 'force-disabled'
export const prefetch: Prefetch = 'partial'版本历史#
| 版本 | 变更 |
|---|---|
v16.3.0 | prefetch 导出已稳定,取代 unstable_prefetch(仅限 Cache Components)。 |