路由段配置(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)。

TypeScript

layout.tsx | page.tsx

export const experimental_ppr = true
// true | false

JavaScript

layout.js | page.js

export const experimental_ppr = true
// true | false

dynamic

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

TypeScript

layout.tsx | page.tsx | route.ts

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

JavaScript

layout.js | page.js | route.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'。

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

提示：

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

dynamicParams

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

TypeScript

layout.tsx | page.tsx

export const dynamicParams = true // true | false,

JavaScript

layout.js | page.js | route.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 时，段使用 流式服务端渲染。

revalidate

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

TypeScript

layout.tsx | page.tsx | route.ts

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

JavaScript

layout.js | page.js | route.js

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 请求的默认值更改为 'no-store'，但保持选择 'force-cache' 或使用正数 revalidate 的 fetch 请求不变。
• number：（以秒为单位）将布局或页面的默认重新验证频率设置为 n 秒。

提示：

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

重新验证频率

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

fetchCache

这是一个高级选项，仅在你特别需要覆盖默认行为时才应使用。

默认情况下，Next.js 将缓存在使用任何 动态 API 之前可访问的任何 fetch() 请求，并且不会缓存在使用动态 API 之后发现的 fetch 请求。

fetchCache 允许你覆盖布局或页面中所有 fetch 请求的默认 cache 选项。

TypeScript

layout.tsx | page.tsx | route.ts

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

JavaScript

layout.js | page.js | route.js

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

• 'auto'（默认）：默认选项，使用它们提供的 cache 选项缓存动态 API 之前的 fetch 请求，不缓存动态 API 之后的 fetch 请求。
• 'default-cache'：允许将任何 cache 选项传递给 fetch，但如果未提供选项，则将 cache 选项设置为 'force-cache'。这意味着即使是动态 API 之后的 fetch 请求也被认为是静态的。
• 'only-cache'：通过将默认值更改为 cache: 'force-cache'（如果未提供选项）并在任何 fetch 请求使用 cache: 'no-store' 时导致错误，确保所有 fetch 请求选择缓存。
• 'force-cache'：通过将所有 fetch 请求的 cache 选项设置为 'force-cache'，确保所有 fetch 请求选择缓存。
• 'default-no-store'：允许将任何 cache 选项传递给 fetch，但如果未提供选项，则将 cache 选项设置为 'no-store'。这意味着即使是动态 API 之前的 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'，因为这可能使相同的 fetch 具有不同的行为。
• 通常建议将共享的父布局保留为 'auto'，并在子段分歧的地方自定义选项。

runtime

我们建议使用 Node.js 运行时来渲染你的应用程序，使用 Edge 运行时来处理中间件。

TypeScript

layout.tsx | page.tsx | route.ts

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

JavaScript

layout.js | page.js | route.js

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

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

preferredRegion

TypeScript

layout.tsx | page.tsx | route.ts

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

JavaScript

layout.js | page.js | route.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 或更高版本。

TypeScript

layout.tsx | page.tsx | route.ts

export const maxDuration = 5

JavaScript

layout.js | page.js | route.js

export const maxDuration = 5

提示：

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

generateStaticParams

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

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

版本历史

版本
v15.0.0-RC	export const runtime = "experimental-edge" 已弃用。提供了 codemod。