路由段配置
路由段选项允许你通过直接导出以下变量来配置 页面、布局 或 路由处理程序 的行为:
选项 | 类型 | 默认值 |
---|---|---|
experimental_ppr | 'true' | 'false' | |
dynamic | 'auto' | 'force-dynamic' | 'error' | 'force-static' | 'auto' |
dynamicParams | boolean | true |
revalidate | false | 0 | number | false |
fetchCache | 'auto' | 'default-cache' | 'only-cache' | 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store' | 'auto' |
runtime | 'nodejs' | 'edge' | 'nodejs' |
preferredRegion | 'auto' | 'global' | 'home' | string | string[] | 'auto' |
maxDuration | number | 由部署平台设置 |
选项
experimental_ppr
为布局或页面启用 部分预渲染 (PPR)。
dynamic
更改布局或页面的动态行为,使其完全静态或完全动态。
值得注意的是:
app
目录中的新模型倾向于在fetch
请求级别进行细粒度的缓存控制,而不是像pages
目录中的getServerSideProps
和getStaticProps
那样在页面级别采用二元的全有或全无模型。dynamic
选项是一种重新采用先前模型的便捷方式,并提供了更简单的迁移路径。
-
'auto'
(默认值):尽可能多地缓存,同时不阻止任何组件选择动态行为。 -
'force-dynamic'
:强制 动态渲染,这将导致路由在每个用户请求时被渲染。此选项相当于:pages
目录中的getServerSideProps()
。- 将布局或页面中每个
fetch()
请求的选项设置为{ cache: 'no-store', next: { revalidate: 0 } }
。 - 将段配置设置为
export const fetchCache = 'force-no-store'
-
'error'
:强制静态渲染并缓存布局或页面的数据,如果任何组件使用 动态函数 或未缓存的数据,则会导致错误。此选项相当于:pages
目录中的getStaticProps()
。- 将布局或页面中每个
fetch()
请求的选项设置为{ cache: 'force-cache' }
。 - 将段配置设置为
fetchCache = 'only-cache', dynamicParams = false
。 dynamic = 'error'
将dynamicParams
的默认值从true
更改为false
。你可以通过手动设置dynamicParams = true
来重新启用为未由generateStaticParams
生成的动态参数动态渲染页面。
-
'force-static'
:通过强制cookies()
、headers()
和useSearchParams()
返回空值,来强制静态渲染并缓存布局或页面的数据。
值得注意的是:
- 有关如何从
getServerSideProps
和getStaticProps
迁移到dynamic: 'force-dynamic'
和dynamic: 'error'
的说明可以在 升级指南 中找到。
dynamicParams
控制访问未通过 generateStaticParams 生成的动态段时会发生什么。
true
(默认值):未包含在generateStaticParams
中的动态段将按需生成。false
:未包含在generateStaticParams
中的动态段将返回 404。
值得注意的是:
- 此选项替代了
pages
目录中getStaticPaths
的fallback: true | false | blocking
选项。- 要在首次访问时静态渲染所有路径,你需要在
generateStaticParams
中返回一个空数组或使用export const dynamic = 'force-static'
。- 当
dynamicParams = true
时,该段使用 流式服务器渲染。- 如果使用了
dynamic = 'error'
和dynamic = 'force-static'
,它会将dynamicParams
的默认值更改为false
。
revalidate
为布局或页面设置默认的重新验证时间。此选项不会覆盖单个 fetch
请求设置的 revalidate
值。
false
(默认值):默认策略是缓存任何将cache
选项设置为'force-cache'
的fetch
请求,或在使用 动态函数 之前发现的请求。在语义上等同于revalidate: Infinity
,这实际上意味着资源应该无限期缓存。单个fetch
请求仍然可以使用cache: 'no-store'
或revalidate: 0
来避免被缓存并使路由动态渲染。或者将revalidate
设置为低于路由默认值的正数来增加路由的重新验证频率。0
:确保布局或页面始终 动态渲染,即使没有发现动态函数或未缓存的数据获取。此选项将不设置cache
选项的fetch
请求的默认值更改为'no-store'
,但保留选择使用'force-cache'
或正数revalidate
的fetch
请求不变。number
:(以秒为单位) 将布局或页面的默认重新验证频率设置为n
秒。
值得注意的是:
- revalidate 值需要是静态可分析的。例如,
revalidate = 600
是有效的,但revalidate = 60 * 10
不是。- 使用
runtime = 'edge'
时,revalidate 值不可用。
重新验证频率
- 单个路由中每个布局和页面的最低
revalidate
值将决定整个路由的重新验证频率。这确保子页面的重新验证频率与其父布局一样频繁。 - 单个
fetch
请求可以设置低于路由默认revalidate
的值,以增加整个路由的重新验证频率。这允许你根据某些条件动态选择某些路由的更频繁重新验证。
fetchCache
这是一个高级选项,只有在你特别需要覆盖默认行为时才应使用。
默认情况下,Next.js 会缓存 在使用任何 动态函数 之前 可访问的任何 fetch()
请求,并且 不会缓存 在使用动态函数 之后 发现的 fetch
请求。
fetchCache
允许你覆盖布局或页面中所有 fetch
请求的默认 cache
选项。
'auto'
(默认值):默认选项是在动态函数之前缓存提供cache
选项的fetch
请求,并且不缓存动态函数之后的fetch
请求。'default-cache'
:允许向fetch
传递任何cache
选项,但如果没有提供选项,则将cache
选项设置为'force-cache'
。这意味着即使动态函数之后的fetch
请求也被视为静态的。'only-cache'
:确保所有fetch
请求选择缓存,方法是在未提供选项时将默认值更改为cache: 'force-cache'
,并在任何fetch
请求使用cache: 'no-store'
时导致错误。'force-cache'
:通过将所有fetch
请求的cache
选项设置为'force-cache'
,确保所有fetch
请求选择缓存。'default-no-store'
:允许向fetch
传递任何cache
选项,但如果没有提供选项,则将cache
选项设置为'no-store'
。这意味着即使动态函数之前的fetch
请求也被视为动态的。'only-no-store'
:通过在未提供选项时将默认值更改为cache: 'no-store'
,并在任何fetch
请求使用cache: 'force-cache'
时导致错误,确保所有fetch
请求选择不缓存。'force-no-store'
:通过将所有fetch
请求的cache
选项设置为'no-store'
,确保所有fetch
请求选择不缓存。这强制每次请求都重新获取所有fetch
请求,即使它们提供了'force-cache'
选项。
跨路由段行为
- 单个路由中的每个布局和页面设置的任何选项都需要彼此兼容。
- 如果同时提供了
'only-cache'
和'force-cache'
,则'force-cache'
优先。如果同时提供了'only-no-store'
和'force-no-store'
,则'force-no-store'
优先。强制选项会改变整个路由的行为,因此具有'force-*'
的单个段会防止由'only-*'
引起的任何错误。 'only-*'
和'force-*'
选项的目的是保证整个路由要么完全静态,要么完全动态。这意味着:- 在单个路由中不允许同时使用
'only-cache'
和'only-no-store'
。 - 在单个路由中不允许同时使用
'force-cache'
和'force-no-store'
。
- 在单个路由中不允许同时使用
- 如果子段提供了
'auto'
或'*-cache'
,父段不能提供'default-no-store'
,因为这可能会导致相同的获取行为不同。
- 如果同时提供了
- 通常建议将共享的父布局保留为
'auto'
,并在子段分叉的地方自定义选项。
runtime
我们建议使用 Node.js 运行时来渲染你的应用程序,并使用 Edge 运行时用于中间件 (仅支持的选项)。
'nodejs'
(默认值)'edge'
了解更多关于 不同运行时 的信息。
preferredRegion
对 preferredRegion
的支持以及支持的区域取决于你的部署平台。
值得注意的是:
- 如果未指定
preferredRegion
,它将继承最近的父布局的选项。- 根布局默认为
all
区域。
maxDuration
默认情况下,Next.js 不限制服务器端逻辑的执行 (渲染页面或处理 API)。
部署平台可以使用 Next.js 构建输出中的 maxDuration
来添加特定的执行限制。
例如,在 Vercel 上。
值得注意的是:此设置需要 Next.js 13.4.10
或更高版本。
值得注意的是:
- 如果使用 服务器操作,请在页面级别设置
maxDuration
以更改页面上使用的所有服务器操作的默认超时。
generateStaticParams
generateStaticParams
函数可以与 动态路由段 结合使用,以定义将在构建时静态生成而不是在请求时按需生成的路由段参数列表。
有关更多详细信息,请参阅 API 参考。