NNext.js 中文网 GitHub

ensureStatic

使用 ensureStatic 路由段配置要求选定的路由输出保持静态,而不是按请求渲染。

ensureStatic 路由段配置要求选定的路由输出是静态的,而不是按请求渲染。从页面或布局中导出它,可对 App Shell、逐链接预取或完整的服务端渲染路由强制执行此要求。

使用它可以确保后续的更改不会向必须保持静态的导航阶段添加请求时的服务端渲染。有关每一级别的完整示例,请参阅保持页面为静态。

小知识:

  • ensureStatic 导出仅在启用 cacheComponents 时有效,否则构建将失败。
  • 从 Client Component 导出 ensureStatic 会抛出错误。
app/blog/layout.tsx
export const ensureStatic = 'navigation'

export default function Layout({ children }: { children: React.ReactNode }) {
  return <>{children}</>
}
app/blog/layout.js
export const ensureStatic = 'navigation'

export default function Layout({ children }) {
  return <>{children}</>
}

参考#

该导出接受 'auto'、'shell'、'prefetch'、'navigation' 或 false。默认值为 'auto',等同于不导出该项。

ensureStatic 控制哪些服务端渲染输出必须是静态的。借助 Partial Prefetching,这些输出可以是 App Shell、可选的逐链接预取,或导航期间渲染的完整路由。这些输出称为导航阶段。每个更严格的级别也包含更早的阶段。

值必须为静态的输出
'auto'(默认值)无额外的静态要求
'shell'App Shell
'prefetch'App Shell 和逐链接预取
'navigation'完整的服务器渲染路由

false 不选择静态级别。它保留正常的渲染行为,并阻止其他段对该路由应用 'shell'、'prefetch' 或 'navigation'。请参阅 false。

'shell'#

要求默认 <Link> 加载的 App Shell 是静态的。如果没有 Partial Prefetching,则不存在 App Shell,因此该值无效,Next.js 会记录一条警告。

shell 可以包含静态或缓存的内容以及 <Suspense> fallback。<Suspense> 之后与请求相关的内容可以在稍后的逐链接预取期间通过 <Link prefetch={true}> 渲染,或在导航期间渲染。

对于单个子树,await prefetch() 通过将对调用的下方代码推迟到逐链接预取或导航,提供了类似的行为。设置 'shell' 可在整个路由范围内强制执行该阶段边界,而无需为每个与请求相关的子树添加 await prefetch()。有关逐子树控制,请参阅将工作推迟到稍后阶段。

小知识:'shell' 并不要求逐链接预取是静态的。如果路由在 await navigation() 之前读取 cookies()、headers() 或 URL 数据,则每个可见的 <Link prefetch={true}> 仍可能触发服务端渲染。如果逐链接预取也必须来自静态输出,请使用 'prefetch'。

'prefetch'#

要求 App Shell 和逐链接预取都是静态的。如果没有 Partial Prefetching,该值不会增加任何要求,链接会保持其正常的完整预取行为。完整预取可以包含与请求相关的数据,并且不保证是静态的。

来自 <Link prefetch={true}> 的逐链接预取可以在用户点击链接之前加载静态或缓存的特定于 URL 的内容。<Suspense> 之后与请求相关的内容会在导航完成路由时渲染。

静态 HTML shell 也可以包含这种静态或缓存的逐链接内容。与逐链接预取不同,它不能包含与请求相关的数据,因为 HTML shell 是预渲染的。

对于单个子树,await navigation() 通过将对调用的下方代码推迟到导航时,提供了类似的行为。设置 'prefetch' 可在整个路由范围内强制执行该阶段边界,而无需为每个与请求相关的子树添加 await navigation()。有关以这种方式塑造单个路由,请参阅保持预取为静态。

要求完整的服务器渲染路由在预渲染期间生成,以便初始加载和客户端导航都使用静态输出。该值仅凭 Cache Components 即可工作,不需要 Partial Prefetching。

要对整个应用要求静态服务端输出,请在根布局上设置 'navigation'。有关级别如何跨路由应用,请参阅跨布局和页面组合级别。

验证#

对于 'shell' 和 'prefetch',<Suspense> 内与请求相关的工作可以移到稍后的导航阶段。这些值不会增加构建验证。当启用即时导航验证时,它可以报告 <Suspense> 之外与请求相关的工作,因为这类工作会阻塞导航。

'navigation' 是最终的服务端渲染阶段,因此不存在更晚的阶段。Next.js 会在 next dev 和 next build 期间都验证其完整的静态输出要求。在开发环境中,错误包含随编辑而更新的源映射堆栈跟踪。构建输出更为简略,因此你可能需要运行 next build --debug-prerender 以获取详细的堆栈跟踪和代码框架。有关开发工作流,请参阅确保即时导航。

在 ensureStatic = 'navigation' 下,以下服务端内容无法通过验证,即使它被包裹在 <Suspense> 中,或该段设置了 instant = false:

  • 未缓存的数据,包括没有 use cache 的 fetch 或数据库调用,以及 connection()。
  • 运行时数据,例如 cookies()、headers() 和服务端的 searchParams。
  • 某个 use cache 作用域,其 expire 少于五分钟、stale 少于 30 秒,或 revalidate 为 0。允许 stale 时间在 30 秒到五分钟之间。
  • 传递给 Client Component 的、依赖于请求的 Promise,无论该组件是否读取它。

这些限制也适用于 generateMetadata 和 generateViewport。

用 use cache 缓存的数据可以被预渲染。prefetch() 和 navigation() 也是允许的,因为静态预渲染会继续穿过它们的阶段边界。

动态路由参数#

使用 'navigation' 时,动态路由必须导出 generateStaticParams() 并返回至少一组完整的参数。每个结果都必须包含路由中的所有动态参数,即使该参数未被使用或仅在 Client Component 中读取。

generateStaticParams() 返回的值在预渲染期间可用。当请求使用了构建时未预渲染的值时,Next.js 会等待静态结果生成后再提供它。

使用 'shell' 或 'prefetch' 时,未预渲染的值会改为提供路由的 fallback shell,并以 <Suspense> fallback 代替其内容,同时 Next.js 在后台生成页面。请参阅使用 Cache Components 的 ISR。

当 generateStaticParams() 缺失或返回不完整的参数集时,构建将失败。请参阅 generateStaticParams 错误指南。

Client Components#

Client Component 可以在浏览器中加载与请求相关的内容。在 <Suspense> 内,允许使用 use(browser()) 和 use(io())。预渲染会包含被推迟内容的 fallback。请参阅仅在浏览器中渲染组件。

也允许使用诸如 useParams() 和 useSearchParams() 之类的客户端 hook。动态路由仍然需要 generateStaticParams()。从 Server Component 传递依赖于请求的 Promise 仍然需要服务端工作,并会产生错误。

false#

借助 Partial Prefetching,false 保留路由的正常渲染行为,并在其他段设置 'shell'、'prefetch' 或 'navigation' 时导致构建失败。可用它来表明某个段不打算进行静态优化。

ensureStatic 与 instant 的区别#

ensureStatic 要求选定的服务端渲染输出避免请求时的工作。当 App Shell、逐链接预取或完整路由必须是静态的时,请使用它。

instant 验证导航是否可以立即更新 UI。缓存或预渲染的 UI 可以满足此要求,而与请求相关的内容稍后在 <Suspense> 之后流式传输。

设置 instant = false 会禁用该路由的即时导航验证。'shell' 和 'prefetch' 值仍会让客户端请求相应的静态输出,但这两个值都不会增加单独的构建验证。即使页面 UI 只在用户点击链接后才渲染,静态预取仍然可以包含父布局、metadata 和 Client Component 预加载提示。'navigation' 值使用单独的完整静态输出验证,instant = false 不会放宽该验证。

跨布局和页面组合级别#

在根布局上设置的级别适用于应用中的每个路由。在其他布局上设置的级别适用于渲染它的每个路由,包括其嵌套布局、页面和并行路由。在一个路由内,该级别覆盖每个段,包括设置该级别的布局之上的那些布局。

不设置导出项或将其设置为 'auto' 与任何级别都兼容,并保留其他段的设置。后代可以设置更严格的静态级别,但不能设置更宽松的:

app/blog/layout.tsx
export const ensureStatic = 'prefetch'
app/blog/[slug]/page.tsx
export const ensureStatic = 'navigation' // 允许,比 'prefetch' 更严格

子段上设置更宽松的级别会导致构建失败:

Terminal
子段不能使用约束更宽松的 `ensureStatic` 覆盖父段。

在父段和子段中混合使用 false 与 'shell'、'prefetch' 或 'navigation' 会失败,并报错:

Terminal
子段不能使用不兼容的 `ensureStatic` 覆盖父段。

一起渲染的并行路由必须设置相同的值、不设置导出项或使用 'auto'。值冲突时会失败,并报错:

Terminal
并行插槽不能设置不兼容的 `ensureStatic`。

TypeScript#

app/blog/layout.tsx
type EnsureStatic = 'auto' | 'shell' | 'prefetch' | 'navigation' | false

export const ensureStatic: EnsureStatic = 'navigation'

版本历史#

版本变更
v16.4.0引入 ensureStatic。
Next.js 中文网