NextJS中文文档 - Route Segment Config
如果启用了
dynamicIO
标志,本页概述的选项将被禁用,并且将来最终会被弃用。
路由段选项允许你通过直接导出以下变量来配置 页面、布局 或 路由处理程序 的行为:
选项 | 类型 | 默认值 |
---|---|---|
experimental_ppr | boolean | |
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)。
tsx
export const experimental_ppr = true
// true | false
jsx
export const experimental_ppr = true
// true | false
dynamic
更改布局或页面的动态行为为完全静态或完全动态。
tsx
export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'
js
export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'
须知:
app
目录中的新模型倾向于在fetch
请求级别上进行细粒度缓存控制,而不是pages
目录中页面级别的getServerSideProps
和getStaticProps
全有或全无模型。dynamic
选项是一种回归到之前模型的方式,提供了更简单的迁移路径。
'auto'
(默认值):默认选项,尽可能多地缓存,同时不阻止组件选择动态行为。'force-dynamic'
:强制动态渲染,这将导致路由在请求时为每个用户渲染。此选项相当于:- 将布局或页面中每个
fetch()
请求的选项设置为{ cache: 'no-store', next: { revalidate: 0 } }
。 - 将段配置设置为
export const fetchCache = 'force-no-store'
- 将布局或页面中每个
'error'
:通过在组件使用动态 API或未缓存数据时引发错误,强制静态渲染并缓存布局或页面的数据。此选项相当于:pages
目录中的getStaticProps()
。- 将布局或页面中每个
fetch()
请求的选项设置为{ cache: 'force-cache' }
。 - 将段配置设置为
fetchCache = 'only-cache', dynamicParams = false
。 dynamic = 'error'
将dynamicParams
的默认值从true
更改为false
。你可以通过手动设置dynamicParams = true
来选择为未由generateStaticParams
生成的动态参数动态渲染页面。
'force-static'
:通过强制cookies
、headers()
和useSearchParams()
返回空值,强制静态渲染并缓存布局或页面的数据。
须知:
dynamicParams
控制访问未使用 generateStaticParams 生成的动态段时会发生什么。
tsx
export const dynamicParams = true // true | false,
js
export const dynamicParams = true // true | false,
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
值。
tsx
export const revalidate = false
// false | 0 | number
js
export const revalidate = false
// false | 0 | number
false
(默认值):默认缓存将cache
选项设置为'force-cache'
的任何fetch
请求,或在使用动态 API之前发现的请求。语义上等同于revalidate: Infinity
,这实际上意味着资源应该无限期缓存。单个fetch
请求仍可使用cache: 'no-store'
或revalidate: 0
来避免被缓存并使路由动态渲染。或者将revalidate
设置为低于路由默认值的正数,以增加路由的重新验证频率。0
:确保布局或页面始终动态渲染,即使没有发现动态 API 或未缓存的数据获取。此选项将不设置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 将缓存在使用任何动态 API之前可访问的任何 fetch()
请求,并且不会缓存在使用动态 API之后发现的 fetch
请求。
fetchCache
允许你覆盖布局或页面中所有 fetch
请求的默认 cache
选项。
tsx
export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'
js
export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'
'auto'
(默认值):默认选项,在动态 API 之前使用提供的cache
选项缓存fetch
请求,并且不缓存动态 API 之后的fetch
请求。'default-cache'
:允许向fetch
传递任何cache
选项,但如果未提供选项,则将cache
选项设置为'force-cache'
。这意味着即使是动态 API 之后的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'
。这意味着即使是动态 API 之前的fetch
请求也被视为动态。'only-no-store'
:确保所有fetch
请求选择退出缓存,如果未提供选项,则将默认值更改为cache: 'no-store'
,如果任何fetch
请求使用cache: 'force-cache'
,则会引发错误。'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 选项会改变整个路由的行为,因此具有'force-*'
的单个段将防止由'only-*'
引起的任何错误。 'only-*'
和'force-*'
选项的目的是保证整个路由要么完全静态,要么完全动态。这意味着:- 单个路由中
'only-cache'
和'only-no-store'
的组合是不允许的。 - 单个路由中
'force-cache'
和'force-no-store'
的组合是不允许的。
- 单个路由中
- 如果子段提供
'auto'
或'*-cache'
,父段不能提供'default-no-store'
,因为这可能导致相同的获取有不同的行为。
- 如果同时提供了
- 通常建议将共享的父布局保留为
'auto'
,并在子段分歧的地方自定义选项。
runtime
我们建议使用 Node.js 运行时渲染你的应用程序,使用 Edge 运行时进行中间件处理。
tsx
export const runtime = 'nodejs'
// 'nodejs' | 'edge'
js
export const runtime = 'nodejs'
// 'nodejs' | 'edge'
'nodejs'
(默认值)'edge'
preferredRegion
tsx
export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']
js
export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']
对 preferredRegion
的支持及支持的区域取决于你的部署平台。
须知:
- 如果未指定
preferredRegion
,它将继承最近父布局的选项。- 根布局默认为
all
区域。
maxDuration
默认情况下,Next.js 不限制服务器端逻辑的执行(渲染页面或处理 API)。 部署平台可以使用 Next.js 构建输出中的 maxDuration
添加特定的执行限制。
注意:此设置需要 Next.js 13.4.10
或更高版本。
tsx
export const maxDuration = 5
js
export const maxDuration = 5
须知:
- 如果使用服务器操作,请在页面级别设置
maxDuration
以更改页面上使用的所有服务器操作的默认超时。
generateStaticParams
generateStaticParams
函数可以与动态路由段结合使用,以定义将在构建时静态生成而不是在请求时按需生成的路由段参数列表。
有关更多详细信息,请参阅 API 参考。
版本历史
版本 | |
---|---|
v15.0.RC | export const runtime = "experimental-edge" 已弃用。提供了代码修改工具。 |