路由段配置

路由段选项允许您通过直接导出以下变量来配置 页面 (Page)、布局 (Layout) 或 路由处理器 (Route Handler) 的行为：

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

须知:

• 配置选项的值目前需要是静态可分析的。例如 revalidate = 600 是有效的，但 revalidate = 60 * 10 则无效。

选项

dynamic

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

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

须知: app 目录中的新模型更倾向于在 fetch 请求级别进行细粒度的缓存控制，而不是 pages 目录中页面级别的 getServerSideProps 和 getStaticProps 的全有或全无模型。dynamic 选项是一种便捷方式，可以回退到以前的模型，并提供更简单的迁移路径。

• 'auto' (默认值): 默认选项，尽可能缓存，同时不阻止任何组件选择动态行为。
• 'force-dynamic': 强制动态渲染和未缓存的数据获取，通过禁用所有 fetch 请求的缓存并始终重新验证。此选项等同于：
  • pages 目录中的 getServerSideProps()。
  • 将布局或页面中每个 fetch() 请求的选项设置为 { cache: 'no-store', next: { revalidate: 0 } }。
  • 将段配置设置为 export const fetchCache = 'force-no-store'。
• 'error': 强制静态渲染并缓存布局或页面的数据，如果任何组件使用 动态函数 (dynamic functions) 或未缓存的数据，则会导致错误。此选项等同于：
  • 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 选项。
• 当 dynamicParams = true 时，该段使用 流式服务器渲染 (Streaming Server Rendering)。
• 如果使用了 dynamic = 'error' 和 dynamic = 'force-static'，会将 dynamicParams 的默认值更改为 false。

revalidate

设置布局或页面的默认重新验证时间。此选项不会覆盖单个 fetch 请求设置的 revalidate 值。

export const revalidate = false
// false | 'force-cache' | 0 | number

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

须知: revalidate 选项仅在 Node.js 运行时 (Node.js Runtime) 可用。这意味着将 revalidate 选项与 runtime = 'edge' 一起使用将无效。

重新验证频率

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

fetchCache

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

runtime

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

• nodejs (默认值)
• edge

了解更多关于 Edge 和 Node.js 运行时 (Edge and Node.js runtimes)。

preferredRegion

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

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

须知:

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

maxDuration

根据您的部署平台，您可能可以为函数使用更高的默认执行时间。此设置允许您在计划限制内选择更高的执行时间。 注意: 此设置需要 Next.js 13.4.10 或更高版本。

export const maxDuration = 5

须知:

• 如果未指定 maxDuration，默认值取决于您的部署平台和计划。

generateStaticParams

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

更多详情请参阅 API 参考。