Skip to main content

路由片段配置

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

¥The Route Segment options allows you to configure the behavior of a Page, Layout, or Route Handler by directly exporting the following variables:

选项类型默认
experimental_ppr'true' | 'false'
dynamic'auto' | 'force-dynamic' | 'error' | 'force-static''auto'
dynamicParamsbooleantrue
revalidatefalse | 0 | numberfalse
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'
maxDurationnumber由部署平台设置

选项​

¥Options

experimental_ppr​

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

¥Enable Partial Prerendering (PPR) for a layout or page.

export const experimental_ppr = true
// true | false
export const experimental_ppr = true
// true | false

dynamic​

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

¥Change the dynamic behavior of a layout or page to fully static or fully dynamic.

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

很高兴知道：app 目录中的新模型支持 fetch 请求级别的细粒度缓存控制，而不是 pages 目录中页面级别的 getServerSideProps 和 getStaticProps 的二进制全有或全无模型。dynamic 选项是一种选择返回到以前的模型的方法，以方便起见并提供更简单的迁移路径。

¥Good to know: The new model in the app directory favors granular caching control at the fetch request level over the binary all-or-nothing model of getServerSideProps and getStaticProps at the page-level in the pages directory. The dynamic option is a way to opt back in to the previous model as a convenience and provides a simpler migration path.

  • 'auto'（默认）：默认选项会尽可能多地缓存，而不阻止任何组件选择动态行为。

    ¥**'auto'** (default): The default option to cache as much as possible without preventing any components from opting into dynamic behavior.

  • 'force-dynamic'：强制 动态渲染，这将导致在请求时为每个用户渲染路由。该选项相当于：

    ¥**'force-dynamic'**: Force dynamic rendering, which will result in routes being rendered for each user at request time. This option is equivalent to:

    • getServerSideProps() 在 pages 目录中。

      ¥getServerSideProps() in the pages directory.

    • 将布局或页面中每个 fetch() 请求的选项设置为 { cache: 'no-store', next: { revalidate: 0 } }。

      ¥Setting the option of every fetch() request in a layout or page to { cache: 'no-store', next: { revalidate: 0 } }.

    • 将段配置设置为 export const fetchCache = 'force-no-store'

      ¥Setting the segment config to export const fetchCache = 'force-no-store'

  • 'error'：如果任何组件使用 动态函数 或未缓存的数据，则会引发错误，从而强制静态渲染并缓存布局或页面的数据。该选项相当于：

    ¥**'error'**: Force static rendering and cache the data of a layout or page by causing an error if any components use dynamic functions or uncached data. This option is equivalent to:

    • getStaticProps() 在 pages 目录中。

      ¥getStaticProps() in the pages directory.

    • 将布局或页面中每个 fetch() 请求的选项设置为 { cache: 'force-cache' }。

      ¥Setting the option of every fetch() request in a layout or page to { cache: 'force-cache' }.

    • 将段配置设置为 fetchCache = 'only-cache', dynamicParams = false。

      ¥Setting the segment config to fetchCache = 'only-cache', dynamicParams = false.

    • dynamic = 'error' 将 dynamicParams 的默认值从 true 更改为 false。你可以通过手动设置 dynamicParams = true 选择重新动态渲染不是由 generateStaticParams 生成的动态参数的页面。

      ¥dynamic = 'error' changes the default of dynamicParams from true to false. You can opt back into dynamically rendering pages for dynamic params not generated by generateStaticParams by manually setting dynamicParams = true.

  • 'force-static'：通过强制 cookies()、headers() 和 useSearchParams() 返回空值来强制静态渲染并缓存布局或页面的数据。

    ¥**'force-static'**: Force static rendering and cache the data of a layout or page by forcing cookies(), headers() and useSearchParams() to return empty values.

很高兴知道：

¥Good to know:

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

    ¥Instructions on how to migrate from getServerSideProps and getStaticProps to dynamic: 'force-dynamic' and dynamic: 'error' can be found in the upgrade guide.

dynamicParams​

控制当访问不是使用 generateStaticParams 生成的动态段时会发生什么情况。

¥Control what happens when a dynamic segment is visited that was not generated with generateStaticParams.

export const dynamicParams = true // true | false,
export const dynamicParams = true // true | false,

  • true（默认）：generateStaticParams 中未包含的动态段是按需生成的。

    ¥**true** (default): Dynamic segments not included in generateStaticParams are generated on demand.

  • false：未包含在 generateStaticParams 中的动态段将返回 404。

    ¥**false**: Dynamic segments not included in generateStaticParams will return a 404.

很高兴知道：

¥Good to know:

  • 该选项替换 pages 目录中 getStaticPaths 的 fallback: true | false | blocking 选项。

    ¥This option replaces the fallback: true | false | blocking option of getStaticPaths in the pages directory.

  • 要在第一次访问时静态渲染所有路径，你需要在 generateStaticParams 中返回一个空数组或利用 export const dynamic = 'force-static'。

    ¥To statically render all paths the first time they're visited, you'll need to return an empty array in generateStaticParams or utilize export const dynamic = 'force-static'.

  • 当 dynamicParams = true 时，该段使用 流式服务器渲染。

    ¥When dynamicParams = true, the segment uses Streaming Server Rendering.

  • 如果使用了 dynamic = 'error' 和 dynamic = 'force-static'，则会将默认的 dynamicParams 更改为 false。

    ¥If the dynamic = 'error' and dynamic = 'force-static' are used, it'll change the default of dynamicParams to false.

revalidate​

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

¥Set the default revalidation time for a layout or page. This option does not override the revalidate value set by individual fetch requests.

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

  • false（默认）：默认启发式缓存任何将 cache 选项设置为 'force-cache' 或在使用 动态函数 之前发现的 fetch 请求。语义上相当于 revalidate: Infinity，这实际上意味着资源应该无限期地缓存。个别 fetch 请求仍然可以使用 cache: 'no-store' 或 revalidate: 0 来避免被缓存并使路由动态渲染。或者将 revalidate 设置为低于路由默认值的正数，以增加路由的重新验证频率。

    ¥**false** (default): The default heuristic to cache any fetch requests that set their cache option to 'force-cache' or are discovered before a dynamic function is used. Semantically equivalent to revalidate: Infinity which effectively means the resource should be cached indefinitely. It is still possible for individual fetch requests to use cache: 'no-store' or revalidate: 0 to avoid being cached and make the route dynamically rendered. Or set revalidate to a positive number lower than the route default to increase the revalidation frequency of a route.

  • 0：确保布局或页面始终为 动态渲染，即使没有发现动态函数或未缓存的数据提取。此选项更改未将 cache 选项设置为 'no-store' 的 fetch 请求的默认值，但保留选择进入 'force-cache' 或按原样使用正 revalidate 的 fetch 请求。

    ¥**0**: Ensure a layout or page is always dynamically rendered even if no dynamic functions or uncached data fetches are discovered. This option changes the default of fetch requests that do not set a cache option to 'no-store' but leaves fetch requests that opt into 'force-cache' or use a positive revalidate as is.

  • number：（很快）将布局或页面的默认重新验证频率设置为 n 秒。

    ¥**number**: (in seconds) Set the default revalidation frequency of a layout or page to n seconds.

很高兴知道：

¥Good to know:

  • 重新验证值需要可静态分析。例如 revalidate = 600 有效，但 revalidate = 60 * 10 无效。

    ¥The revalidate value needs to be statically analyzable. For example revalidate = 600 is valid, but revalidate = 60 * 10 is not.

  • 使用 runtime = 'edge' 时，重新验证值不可用。

    ¥The revalidate value is not available when using runtime = 'edge'.

重新验证频率​

¥Revalidation Frequency

  • 单个路由的每个布局和页面的最低 revalidate 将决定整个路由的重新验证频率。这可确保子页面与其父布局一样频繁地重新验证。

    ¥The lowest revalidate across each layout and page of a single route will determine the revalidation frequency of the entire route. This ensures that child pages are revalidated as frequently as their parent layouts.

  • 各个 fetch 请求可以设置比路由默认 revalidate 更低的 revalidate，以增加整个路由的重新验证频率。这使你可以根据某些条件动态选择对某些路由进行更频繁的重新验证。

    ¥Individual fetch requests can set a lower revalidate than the route's default revalidate to increase the revalidation frequency of the entire route. This allows you to dynamically opt-in to more frequent revalidation for certain routes based on some criteria.

fetchCache​

This is an advanced option that should only be used if you specifically need to override the default behavior.

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

¥By default, Next.js will cache any fetch() requests that are reachable before any dynamic functions are used and will not cache fetch requests that are discovered after dynamic functions are used.

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

¥fetchCache allows you to override the default cache option of all fetch requests in a layout or page.

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'

  • 'auto'（默认）：默认选项是在动态函数之前使用它们提供的 cache 选项缓存 fetch 请求，并且在动态函数之后不缓存 fetch 请求。

    ¥**'auto'** (default): The default option to cache fetch requests before dynamic functions with the cache option they provide and not cache fetch requests after dynamic functions.

  • 'default-cache'：允许将任何 cache 选项传递给 fetch，但如果未提供任何选项，则将 cache 选项设置为 'force-cache'。这意味着即使动态函数之后的 fetch 请求也被视为静态。

    ¥**'default-cache'**: Allow any cache option to be passed to fetch but if no option is provided then set the cache option to 'force-cache'. This means that even fetch requests after dynamic functions are considered static.

  • 'only-cache'：如果未提供选项，则通过将默认值更改为 cache: 'force-cache' 来确保所有 fetch 请求选择缓存，如果任何 fetch 请求使用 cache: 'no-store'，则会导致错误。

    ¥**'only-cache'**: Ensure all fetch requests opt into caching by changing the default to cache: 'force-cache' if no option is provided and causing an error if any fetch requests use cache: 'no-store'.

  • 'force-cache'：通过将所有 fetch 请求的 cache 选项设置为 'force-cache'，确保所有 fetch 请求选择缓存。

    ¥**'force-cache'**: Ensure all fetch requests opt into caching by setting the cache option of all fetch requests to 'force-cache'.

  • 'default-no-store'：允许将任何 cache 选项传递给 fetch，但如果未提供任何选项，则将 cache 选项设置为 'no-store'。这意味着即使动态函数之前的 fetch 请求也被认为是动态的。

    ¥**'default-no-store'**: Allow any cache option to be passed to fetch but if no option is provided then set the cache option to 'no-store'. This means that even fetch requests before dynamic functions are considered dynamic.

  • 'only-no-store'：如果未提供选项，则通过将默认值更改为 cache: 'no-store' 来确保所有 fetch 请求选择退出缓存，如果任何 fetch 请求使用 cache: 'force-cache'，则会导致错误

    ¥**'only-no-store'**: Ensure all fetch requests opt out of caching by changing the default to cache: 'no-store' if no option is provided and causing an error if any fetch requests use cache: 'force-cache'

  • 'force-no-store'：通过将所有 fetch 请求的 cache 选项设置为 'no-store'，确保所有 fetch 请求选择退出缓存。这会强制每个请求重新获取所有 fetch 请求，即使它们提供了 'force-cache' 选项。

    ¥**'force-no-store'**: Ensure all fetch requests opt out of caching by setting the cache option of all fetch requests to 'no-store'. This forces all fetch requests to be re-fetched every request even if they provide a 'force-cache' option.

跨路由路段行为​

¥Cross-route segment behavior

  • 跨单个路由的每个布局和页面设置的任何选项都需要彼此兼容。

    ¥Any options set across each layout and page of a single route need to be compatible with each other.

    • 如果 'only-cache' 和 'force-cache' 都提供，则 'force-cache' 获胜。如果同时提供了 'only-no-store' 和 'force-no-store'，则 'force-no-store' 获胜。强制选项会更改整个路由的行为，因此带有 'force-*' 的单个线段将防止 'only-*' 引起的任何错误。

      ¥If both the 'only-cache' and 'force-cache' are provided, then 'force-cache' wins. If both 'only-no-store' and 'force-no-store' are provided, then 'force-no-store' wins. The force option changes the behavior across the route so a single segment with 'force-*' would prevent any errors caused by 'only-*'.

    • 'only-*' 和 'force-*' 选项的目的是保证整个路由是完全静态或完全动态的。这意味着：

      ¥The intention of the 'only-*' and 'force-*' options is to guarantee the whole route is either fully static or fully dynamic. This means:

      • 不允许在一条路由中组合使用 'only-cache' 和 'only-no-store'。

        ¥A combination of 'only-cache' and 'only-no-store' in a single route is not allowed.

      • 不允许在一条路由中组合使用 'force-cache' 和 'force-no-store'。

        ¥A combination of 'force-cache' and 'force-no-store' in a single route is not allowed.

    • 如果子级提供 'auto' 或 '*-cache'，则父级无法提供 'default-no-store'，因为这可能会使相同的提取具有不同的行为。

      ¥A parent cannot provide 'default-no-store' if a child provides 'auto' or '*-cache' since that could make the same fetch have different behavior.

  • 通常建议将共享父布局保留为 'auto' 并自定义子段分歧的选项。

    ¥It is generally recommended to leave shared parent layouts as 'auto' and customize the options where child segments diverge.

runtime​

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

¥We recommend using the Node.js runtime for rendering your application, and the Edge runtime for Middleware (only supported option).

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

  • 'nodejs'（默认）

    ¥**'nodejs'** (default)

  • 'edge'

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

¥Learn more about the different runtimes.

preferredRegion​

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

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

¥Support for preferredRegion, and regions supported, is dependent on your deployment platform.

很高兴知道：

¥Good to know:

  • 如果未指定 preferredRegion，它将继承最近的父布局的选项。

    ¥If a preferredRegion is not specified, it will inherit the option of the nearest parent layout.

  • 根布局默认为 all 区域。

    ¥The root layout defaults to all regions.

maxDuration​

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

¥By default, Next.js does not limit the execution of server-side logic (rendering a page or handling an API). Deployment platforms can use maxDuration from the Next.js build output to add specific execution limits. For example, on Vercel.

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

¥Note: This settings requires Next.js 13.4.10 or higher.

export const maxDuration = 5
export const maxDuration = 5

很高兴知道：

¥Good to know:

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

    ¥If using Server Actions, set the maxDuration at the page level to change the default timeout of all Server Actions used on the page.

generateStaticParams​

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

¥The generateStaticParams function can be used in combination with dynamic route segments to define the list of route segment parameters that will be statically generated at build time instead of on-demand at request time.

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

¥See the API reference for more details.