Good to know:

• 如果 cacheComponents 标志开启，本页列出的选项将被禁用，并最终在未来被弃用。
• 路由段选项仅在服务器组件页面（Server Component Pages）、布局（Layouts）或路由处理器（Route Handlers）中生效。
• generateStaticParams 不能在 'use client' 文件内部使用。

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

选项

dynamic

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

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

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

Good to know: 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'。

• 'force-static'：强制静态渲染并缓存布局或页面的数据，通过强制 cookies、headers() 和 useSearchParams() 返回空值。在使用 force-static 渲染的页面或布局中，可以进行 revalidate、revalidatePath 或 revalidateTag。

Good to know:

• 关于 如何从 getServerSideProps 和 getStaticProps 迁移 到 dynamic: 'force-dynamic' 和 dynamic: 'error' 的说明，可以在 升级指南 中找到。

dynamicParams

控制当访问一个未使用 generateStaticParams 生成的动态段时会发生什么。

export const dynamicParams = true // true | false

export const dynamicParams = true // true | false

• true (默认)：未包含在 generateStaticParams 中的动态段将按需生成。
• false：未包含在 generateStaticParams 中的动态段将返回 404 错误。

Good to know:

• 此选项替换了 pages 目录中 getStaticPaths 的 fallback: true | false | blocking 选项。
• 要在首次访问时静态渲染所有路径，您需要在 generateStaticParams 中返回一个空数组，或使用 export const dynamic = 'force-static'。
• 当 dynamicParams = true 时，该段使用 流式服务器渲染（Streaming Server Rendering）。

revalidate

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

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

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

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

Good to know:

• revalidate 值需要是静态可分析的。例如 revalidate = 600 是有效的，但 revalidate = 60 * 10 是无效的。
• 当使用 runtime = 'edge' 时，revalidate 值不可用。
• 在开发模式下（Development），页面 总是 按需渲染且从不缓存。这使您可以立即看到更改，而无需等待重新验证周期过去。

重新验证频率

• 单个路由中每个布局和页面的最低 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'

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

runtime

我们建议使用 Node.js 运行时来渲染您的应用程序。此选项不能在 代理（Proxy） 中使用。

Good to know: runtime: 'edge' 不支持 缓存组件（Cache Components）。

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

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

• 'nodejs' (默认)
• 'edge'

preferredRegion

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

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

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

Good to know:

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

maxDuration

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

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

export const maxDuration = 5

export const maxDuration = 5

Good to know:

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

generateStaticParams

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

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

版本历史