路由片段配置

路由片段选项允许您通过直接导出以下变量来配置 页面、布局 或 路由处理程序 的行为。

选项

experimental_ppr

为布局或页面启用 部分预渲染 (PPR)。

export const experimental_ppr = true
// true | false

dynamic

将布局或页面的动态行为更改为完全静态或完全动态。

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

值得注意的是：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'：强制静态渲染并缓存布局或页面的数据，如果任何组件使用 动态 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() 返回空值。

值得注意的是:

• 有关如何从getServerSideProps和getStaticProps迁移到dynamic: 'force-dynamic'和dynamic: 'error'的说明，请参阅升级指南。

dynamicParams

控制访问未通过generateStaticParams生成的动态片段时发生的情况。

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值。

export const revalidate = false
// false | 0 | number

• false（默认）：缓存任何将cache选项设置为'force-cache'或在使用动态API之前发现的fetch请求的默认启发式方法。在语义上等效于revalidate: Infinity，这意味着资源应无限期缓存。单个fetch请求仍然可以使用cache: 'no-store'或revalidate: 0来避免被缓存并使路由动态渲染。或者将revalidate设置为小于路由默认值的正数，以提高路由的重新验证频率。
• 0：即使没有发现动态API或未缓存的数据获取，也确保始终动态渲染布局或页面。此选项更改了未设置cache选项的fetch请求的默认值，但保留了选择加入'force-cache'或使用正revalidate的fetch请求。
• number：（以秒为单位）将布局或页面的默认重新验证频率设置为n秒。

值得注意的是:

• 重新验证值需要是静态可分析的。例如revalidate = 600是有效的，但revalidate = 60 * 10无效。
• 使用runtime = 'edge'时，重新验证值不可用。
• 在开发环境中，页面始终按需渲染，并且从未缓存。这使您可以立即查看更改，而无需等待重新验证周期过去。

重新验证频率

• 单个路由的每个布局和页面的最低revalidate将决定整个路由的重新验证频率。这确保子页面与其父布局一样频繁地重新验证。
• 单个fetch请求可以设置低于路由的默认revalidate的值，以提高整个路由的重新验证频率。这允许您根据某些条件动态选择加入更频繁的某些路由的重新验证。

fetchCache

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

runtime

我们建议使用Node.js运行时来渲染您的应用程序，并使用Edge运行时来使用中间件（唯一支持的选项）。

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

• 'nodejs'（默认）
• 'edge'

了解有关不同运行时的更多信息。

preferredRegion

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

对preferredRegion的支持以及支持的区域取决于您的部署平台。

值得注意的是:

• 如果未指定preferredRegion，它将继承最近的父布局的选项。
• 根布局默认为all区域。

maxDuration

默认情况下，Next.js不会限制服务器端逻辑（渲染页面或处理API）的执行。部署平台可以使用Next.js构建输出中的maxDuration来添加特定的执行限制。例如，在Vercel上。

注意：此设置需要Next.js 13.4.10或更高版本。

export const maxDuration = 5

值得注意的是:

• 如果使用服务器操作，请在页面级别设置maxDuration以更改页面上使用的所有服务器操作的默认超时。

generateStaticParams

generateStaticParams 函数可以与动态路由片段结合使用，以定义将在构建时静态生成而不是在请求时按需生成的路由片段参数列表。

有关更多详细信息，请参阅API 参考。

版本历史