NNext.js 中文网 GitHub

缓存

了解如何在 Next.js 中缓存数据和 UI

本页介绍使用 Cache Components 进行缓存,它是通过在 next.config.ts 文件中设置 cacheComponents: true 来启用的。如果你没有使用 Cache Components,请参阅缓存与重新验证(旧模型)指南。

缓存是一种用于存储数据获取和其他计算结果的技术,这样对相同数据的后续请求就能更快地得到响应,而无需重复执行工作。

启用 Cache Components#

使用推荐的 create-next-app 默认配置创建的新 App Router 应用已经启用了 Cache Components 和 Partial Prefetching。

要在现有或手动创建的应用中启用它,请将 cacheComponents 和 partialPrefetching 选项添加到你的 Next 配置文件中:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

export default nextConfig
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  cacheComponents: true,
  partialPrefetching: true,
}

module.exports = nextConfig

请显式设置 partialPrefetching。如果不设置,会记录一条警告,因为 Cache Components 的首个版本并不包含 Partial Prefetching。只有在迁移一个在 Partial Prefetching 之前就采用了 Cache Components 的应用时才将其设为 false。这两个功能将在下一个主要版本中全面启用,届时这些选项将被移除。

小知识: 启用 Cache Components 后,GET Route Handlers 遵循与页面相同的预渲染模型。有关详情,请参阅使用 Cache Components 的 Route Handlers。

用法#

use cache 指令会缓存异步函数和组件的返回值。你可以在两个层级上应用它:

  • 数据层级:缓存获取或计算数据的函数(例如 getProducts()、getUser(id))
  • UI 层级:缓存整个组件或页面(例如 async function BlogPosts())

缓存指令为结果赋予一个生命周期,Next.js 将其用于基于时间的重新验证和渲染优化。关于变更后的按需重新验证,请参阅重新验证。关于缓存结果如何成为静态外壳的一部分并可能被包含在预取中,请参阅预渲染。

小知识: 我们建议将每个缓存指令与 cacheLife 搭配使用。如果不搭配,则会应用隐式的 default 配置。

参数以及从父作用域捕获的任何值都会自动成为缓存键的一部分,这意味着不同的输入会产生不同的缓存条目。关于条目包含的内容,请参阅缓存输出;关于哪些内容可以缓存以及参数如何工作的详细信息,请参阅序列化要求与约束。

数据层级缓存#

要缓存获取数据的异步函数,请在函数体顶部添加 use cache 指令:

app/lib/data.ts
import { cacheLife } from 'next/cache'

export async function getUsers() {
  'use cache'
  cacheLife('hours')
  return db.query('SELECT * FROM users')
}

当相同的数据被多个组件使用,或你希望将数据与 UI 分开缓存时,数据层级缓存非常有用。

UI 层级缓存#

要缓存整个组件、页面或布局,请在组件或页面主体顶部添加 use cache 指令:

app/page.tsx
import { cacheLife } from 'next/cache'

export default async function Page() {
  'use cache'
  cacheLife('hours')

  const users = await db.query('SELECT * FROM users')

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

如果你在文件顶部添加 "use cache",该文件中的所有导出函数都会被缓存。

流式传输未缓存的数据#

对于从异步来源(例如 API、数据库或任何其他异步操作)获取数据,并且每次请求都需要最新数据的组件,请不要使用 "use cache"。

相反,请将组件包裹在 <Suspense> 中并提供一个回退 UI。回退 UI 会随预渲染外壳一起交付,而异步工作在请求时运行。

page.tsx
import { Suspense } from 'react'

async function LatestPosts() {
  const data = await fetch('https://api.example.com/posts')
  const posts = await data.json()
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

export default function Page() {
  return (
    <>
      <h1>My Blog</h1>
      <Suspense fallback={<p>Loading posts...</p>}>
        <LatestPosts />
      </Suspense>
    </>
  )
}

例如,<p>Loading posts...</p> 会包含在静态外壳中,而帖子列表会在请求时流式传入。

如果未缓存的读取周围没有 <Suspense> 边界,开发浮层会显示 blocking-route 洞察,并给出此修复建议:

小知识: 每张修复卡片都链接到一份详细的演练,包含模式、代码示例和权衡取舍。点击卡片即可深入了解。

<Suspense> 在异步工作完成期间提供回退 UI,但它本身并不会让组件选择动态渲染。如果一个组件只执行同步工作,无论它是否被包裹在 <Suspense> 中,都会在预渲染期间完成。

使用运行时 API#

运行时 API 需要只有在用户发起请求时才可用的信息。这些包括:

访问运行时 API 的组件应包裹在 <Suspense> 中:

page.tsx
import { cookies } from 'next/headers'
import { Suspense } from 'react'

async function UserGreeting() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')?.value || 'light'
  return <p>Your theme: {theme}</p>
}

export default function Page() {
  return (
    <>
      <h1>Dashboard</h1>
      <Suspense fallback={<p>Loading...</p>}>
        <UserGreeting />
      </Suspense>
    </>
  )
}

没有 <Suspense> 的运行时 API 访问会在开发浮层中显示相同的 blocking-route 洞察,并给出相同的修复建议:

依赖运行时的数据仍然可以通过 "use cache: private" 获得缓存生命周期,这是 Cache Components 附带的另一个变体。它为直接读取 cookies、headers 或 searchParams 的函数赋予生命周期,使其可以被包含在预取中。

下一节展示 use cache: private 的一种替代方案:提取运行时值并将其传递给共享的缓存函数。

将运行时值传递给缓存函数#

你可以从运行时 API 中提取值,并将它们作为参数传递给缓存函数:

app/profile/page.tsx
import { cookies } from 'next/headers'
import { Suspense } from 'react'

export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <ProfileContent />
    </Suspense>
  )
}

// 组件(未缓存)读取运行时数据
async function ProfileContent() {
  const session = (await cookies()).get('session')?.value
  return <CachedContent sessionId={session} />
}

// 缓存组件通过 prop 接收提取的值
async function CachedContent({ sessionId }: { sessionId: string }) {
  'use cache'
  // sessionId 成为缓存键的一部分
  const data = await fetchUserData(sessionId)
  return <div>{data}</div>
}

在请求时,如果找不到匹配的缓存条目,<CachedContent /> 就会执行,并将结果存储起来供以后具有相同 sessionId 的请求使用。

小知识: 由于 <CachedContent /> 受请求数据限制,它不会被添加到预渲染的静态外壳中。在运行时,它默认采用内存缓存,这种缓存不会在无服务器请求之间持久化,因此它可能会在每个请求上重新求值。如需持久、共享的缓存,请使用 'use cache: remote'。

通过这种模式,预取可以在客户端导航期间使用用户的真实会话预渲染 <CachedContent />,并在点击之前就准备好结果。即使服务端的条目很少在请求之间保留,这种方式也能工作,因为你赋予的生命周期使结果能够加入预取,在预取中客户端会在其 cacheLife stale 窗口内将其视为最新。

静态、缓存与流式#

下面是一个完整的示例,展示静态内容、缓存的动态内容和流式动态内容如何在同一个页面上协同工作:

app/blog/page.tsx
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
import Link from 'next/link'

export default function BlogPage() {
  return (
    <>
      
      <header>
        <h1>Our Blog</h1>
        <nav>
          <Link href="/">Home</Link> | <Link href="/about">About</Link>
        </nav>
      </header>

      
      <BlogPosts />

      
      <Suspense fallback={<p>Loading your preferences...</p>}>
        <UserPreferences />
      </Suspense>
    </>
  )
}

type Post = { id: string; title: string; author: string; date: string }

// 所有人看到相同的博客文章(每小时重新验证一次)
async function BlogPosts() {
  'use cache'
  cacheLife('hours')
  cacheTag('posts')

  const res = await fetch('https://api.vercel.app/blog')
  const posts: Post[] = await res.json()

  return (
    <section>
      <h2>Latest Posts</h2>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>
            <h3>{post.title}</h3>
            <p>
              By {post.author} on {post.date}
            </p>
          </li>
        ))}
      </ul>
    </section>
  )
}

// 依赖于 cookie 中存储的值的 UI
async function UserPreferences() {
  const theme = (await cookies()).get('theme')?.value || 'light'
  const favoriteCategory = (await cookies()).get('category')?.value

  return (
    <aside>
      <p>Your theme: {theme}</p>
      {favoriteCategory && <p>Favorite category: {favoriteCategory}</p>}
    </aside>
  )
}

在预渲染期间,头部(静态)和博客文章(使用 use cache 缓存)连同用户偏好的回退 UI 一起成为静态外壳的一部分。存储在 cookie 中的用户偏好 UI 会在请求时流式传入。

在这里读取 cookies() 并不会像以前的渲染模型那样让整个路由选择动态渲染。Suspense 边界在运行时访问流式传入的位置提供回退 UI,而静态和缓存的内容仍然会随初始 HTML 一起交付。

正如 <Suspense> 包围异步访问一样,错误边界(error boundary)包围错误:将它们包裹在可能在渲染期间出错的子树周围。使用 catchError 实现组件级边界,或使用 error.js 文件约定实现路由级边界。

在构建时请注意,在 generateMetadata 和 generateViewport 内部,未缓存的获取或运行时数据访问会显示与页面中相同的洞察和错误,引导你实现预期的渲染。对于同时包含已知和未知参数值的增量静态再生成,请参阅结合 Cache Components 的 ISR。

随机值与时间戳#

像 Math.random()、Date.now() 或 crypto.randomUUID() 这样的操作每次执行都会产生不同的值。Cache Components 要求你显式处理这些情况。

小知识: performance.now() 用于遥测,因此 Next.js 不会将其视为需要防护的值。请将它用于计时,并把结果传给你的日志或指标系统,而不是将其渲染出来。

要为每个请求生成唯一值,请在调用这些操作之前调用 connection() 来推迟到请求时,并将组件包裹在 <Suspense> 中:

page.tsx
import { connection } from 'next/server'
import { Suspense } from 'react'

async function UniqueContent() {
  await connection()
  const uuid = crypto.randomUUID()
  return <p>Request ID: {uuid}</p>
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <UniqueContent />
    </Suspense>
  )
}

或者,你可以缓存结果,这样所有用户都会看到相同的值,直到重新验证:

page.tsx
export default async function Page() {
  'use cache'
  const buildId = crypto.randomUUID()
  return <p>Build ID: {buildId}</p>
}

你无需记住哪些操作具有这种行为。开发浮层会显示 blocking-prerender-random、blocking-prerender-current-time 或 blocking-prerender-crypto 洞察(取决于具体调用),并给出以下修复建议:

可预测的值#

与可能在各次渲染之间变化的随机值和时间戳不同,模块导入、同步 I/O 和纯计算每次运行都会产生相同的结果。仅使用这些操作的组件会自动预渲染,其输出会在构建时成为静态 HTML 的一部分。

page.tsx
import fs from 'node:fs'

export default async function Page() {
  const constants = await import('./constants.json')
  const content = fs.readFileSync('./config.json', 'utf-8')
  const items = JSON.parse(content).items ?? []

  return (
    <div>
      <h1>{constants.appName}</h1>
      <ul>
        {items.map((item) => (
          <li key={item.id}>{item.value}</li>
        ))}
      </ul>
    </div>
  )
}

小知识: 这包括对具有同步 API 的嵌入式数据库的查询,例如 better-sqlite3 或 Node.js 内置的 node:sqlite。如果你需要从同步源获取每个请求的数据,请在查询之前调用 connection()。

某些异步 API 会读取不依赖传入请求的本地资源,例如字体或配置文件。当这些资源预期对每个请求都相同时,请在模块作用域读取一次,而不是在渲染期间读取

如果数据应在渲染期间计算并在请求之间重用,请将读取操作包裹在 use cache 中。如果数据依赖传入的请求或预期会随时间变化,请在请求时渲染期间读取它。

page.tsx
import { readFile } from 'node:fs/promises'

const content = await readFile('./config.json', 'utf-8')
const items = JSON.parse(content).items ?? []

export default function Page() {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.value}</li>
      ))}
    </ul>
  )
}

在此示例中,配置文件预期对每个请求都相同,因此它在模块作用域中被读取一次。在组件内部调用 await readFile() 会被视为未缓存的数据,必须要么在 use cache 中访问,要么放在 <Suspense> 边界之后。由于此文件不依赖请求且预期不会变化,模块作用域是最简单的选择。

预渲染#

在构建时,Next.js 会渲染你的路由组件树。每个组件的处理方式取决于它所使用的 API:

  • use cache:结果会被缓存并包含在静态外壳中,只要其生命周期不太短
  • <Suspense>:回退 UI 包含在静态外壳中,而内容在请求时流式传入
  • 可预测的值:模块导入、fs.readFileSync 和纯计算在预渲染期间完成,并自动包含在静态外壳中
  • 随机值与时间戳:使用 connection() + <Suspense> 为每个请求获取唯一值,或使用 use cache 在用户之间共享一个值

这会生成一个静态外壳,其中包含用于初始页面加载的 HTML 和用于客户端导航的序列化 RSC Payload,确保无论用户是直接导航到该 URL 还是从另一个页面跳转过来,浏览器都能立即收到完全渲染的内容。这种渲染方式称为部分预渲染(Partial Prerendering,PPR),是 Cache Components 的默认行为。

生成的每个静态外壳都可以直接从 CDN 提供,而无需访问上游服务器。这使得直接导航即时完成。

路由静态外壳中包含的内容取决于构建时已知的信息。当路由的动态参数已知时,外壳包含该具体内容,任何剩余的未缓存数据或运行时数据仍在其 <Suspense> 回退之后流式传入。当参数未知时,可重用的、与 URL 无关的版本就是 App Shell:相同的静态外壳,只是与参数相关的部分留在各自的回退之后。增量静态再生成会在首次访问后填充具体版本。

Next.js 要求你显式处理无法在预渲染期间完成的组件。它会在开发浮层和开发服务器控制台中显示一条验证洞察,指出路由名称并给出修复建议(缓存该访问、将其移入 <Suspense> 边界,或让该路由退出预渲染)。这种验证确保每个路由都会生成静态外壳,从而使直接导航保持即时。

🎥 观看: 为什么需要部分预渲染及其工作原理 → YouTube(10 分钟)。

最大化静态外壳#

异步工作在组件树中放置得越深,页面中可被预渲染的部分就越多。这是 Cache Components 所推崇的结构模式:一种值得普遍应用的通用实践,也是后续即时导航和预取的基础。它适用于所有运行时 API以及像数据获取这样的异步操作。

考虑一个在顶层解构 params 的布局:

app/shop/[slug]/layout.tsx
export default async function Layout({
  children,
  params,
}: LayoutProps<'/shop/[slug]'>) {
  const { slug } = await params

  return (
    <div>
      <Sidebar />
      <h1>{slug}</h1>
      {children}
    </div>
  )
}

如果此参数是动态的(未由 generateStaticParams 提供),它就是运行时数据,该布局无法被预渲染。

不过,通常可以在组件树更靠下的位置读取参数值。不要在布局层级等待,而是将 params 的 Promise 向下传递,并在那里等待:

app/shop/[slug]/layout.tsx
import { Suspense } from 'react'

// 非异步:此布局从不等待 params
export default function Layout({
  children,
  params,
}: LayoutProps<'/shop/[slug]'>) {
  return (
    <div>
      <Sidebar />
      <Suspense fallback={<h1>Loading...</h1>}>
        
        {params.then(({ slug }) => (
          <SlugHeading slug={slug} />
        ))}
      </Suspense>
      {children}
    </div>
  )
}

function SlugHeading({ slug }: { slug: string }) {
  return <h1>{slug}</h1>
}

现在 <Sidebar />、{children} 和 Suspense 回退都属于静态外壳的一部分。只有 SlugHeading 会在请求时流式传入。你也可以传递整个 params Promise,并在子组件中等待它。

同样的原则也适用于 cookies()、headers()、searchParams 和数据获取。有关相关模式,请参阅使用 React.cache 复用数据。

有关完整的工作流程,请参阅优化静态外壳。

即时导航#

Cache Components 在 16.0.0 中发布时带有验证机制,可确保直接访问路由时会生成静态外壳。客户端导航则不同:覆盖直接访问的 <Suspense> 边界在导航过渡期间可能不在渲染范围内。当框架介入时,更容易把这种结构做对。Cache Components 现在也会验证这些导航,为你提供洞察和错误,引导你使得到达你路由的导航变得即时。例如,将数据包裹在 <Suspense> 中、用 use cache 缓存它,或改变访问发生的位置。

阅读即时导航指南以了解示例和检查工具。

预取#

启用 Partial Prefetching 后,路由器默认会预取每个路由的 App Shell。App Shell 包括静态内容以及从 cookies() 和 headers() 派生的会话数据。要同时预取依赖于链接 URL 数据的缓存内容(例如 searchParams 或动态 params),请在该链接上设置 prefetch={true}。

当 <Link prefetch={true}> 指向一个启用了 Partial Prefetching 的路由时,Next.js 会在预取时再次渲染该路由的组件树,这一次会解析目标 URL。同样的规则仍然适用,但由于其 searchParams 和 params 已进入作用范围,现在组件树中有更多部分可以解析:

  • 使用从运行时 API 提取的值(作为参数传入)调用的 use cache 会加入按链接的预取
  • use cache: private 在服务端执行,直接读取运行时数据,并将结果作为按链接预取的一部分缓存到浏览器中
  • <Suspense> 回退会保留在预取的 UI 中,而未缓存的内容会在请求时流式传入

这种按链接的预取包括在目标 URL 已知之后才能解析的缓存内容。其代价是每个可预取链接都会产生一次服务端调用。

例如,以一个从 URL 读取 searchParams 的搜索页面为例:

app/search/page.tsx
import { Suspense } from 'react'

export default function SearchPage(props: PageProps<'/search'>) {
  return (
    <Suspense fallback={<p>Loading results...</p>}>
      <Results searchParams={props.searchParams} />
    </Suspense>
  )
}

async function Results({
  searchParams,
}: Pick<PageProps<'/search'>, 'searchParams'>) {
  const { q } = await searchParams
  const results = await search(q)
  return (
    <ul>
      {results.map((result) => (
        <li key={result.id}>{result.title}</li>
      ))}
    </ul>
  )
}

async function search(query: string | string[] | undefined) {
  'use cache'
  return db.search(query)
}

在直接访问时,<Results> 会在回退之后流式传入。

当指向 /search?q=shoes 的 <Link> 被预取时,框架会从链接的 URL 中解析 searchParams,因此缓存的 search 结果会在点击之前就包含在运行时预渲染中。然后浏览器会重用该结果,直到其 stale 时间过去或 searchParams 发生变化。

请参阅采用 Partial Prefetching以了解 <Link> 预取的行为方式以及如何采用它。

有关完整模式,请参阅优化预取指南;有关所有模式,请参阅 prefetch 参考。

缓存内容的存储位置#

缓存函数的输出会在构建时或运行时被序列化为 RSC payload。其他一切功能都基于这个 payload 工作。Next.js 会将其渲染为 HTML、保存在服务端或远程存储中,或发送到浏览器,而 cacheLife 设置每份副本保持最新的时长:

  • 预渲染输出。 payload 会被渲染为 HTML,在自托管时 HTML 和 RSC payload 存储在磁盘上,或存储在 CDN 之后你平台的持久存储中。直接访问获得 HTML,客户端导航获得 RSC payload。它们共同构成构建时的静态外壳以及 ISR 升级后的具体页面,由 revalidate 和 expire 控制何时重新构建。
  • 共享存储。 默认情况下,结果保存在每个实例的内存存储中,在无服务器环境中这是临时的。use cache: remote 会将其移动到跨实例共享的持久缓存处理器中,这种网络往返只有在高命中率下才划算。
  • 浏览器。 payload 包含在为客户端导航或预取发送的 RSC 中,浏览器会在其 stale 窗口内保持其为最新。use cache: private 的结果只存在于此。

小知识: 读取 cookies() 或 headers() 的 App Shell 是特定于会话的,它在客户端按会话缓存,而不是在共享的服务端缓存中。

所有这些存储都限定在单次部署范围内。新的部署会重新开始,构建新的预渲染结果,use cache 条目不会延续,即使是持久的 remote 条目也是如此,因为缓存键包含构建 ID。有关各环境的行为,请参阅运行时缓存注意事项;有关配置服务端缓存,请参阅自托管。

增量静态再生成#

在带有动态参数段的路由中,generateStaticParams 会在构建时预渲染你列出的 URL。任何其他 URL 都会立即获得 App Shell,然后在后台使用其现已已知的参数进行升级,并为下一位访问者缓存。

有关完整演练,请参阅结合 Cache Components 的 ISR。

机器人与爬虫#

使用部分预渲染时,元数据可以是动态的,而页面的其余部分被预渲染为静态外壳。外壳会立即交付,元数据随后流式传入。某些机器人和爬虫无法处理这种情况,它们需要看到包含在文档 <head> 标签中的元数据。Next.js 会通过其用户代理检测它们,跳过静态外壳,并在请求时动态渲染页面。

在构建时预渲染期间可用的数据源在请求时也必须可用。否则渲染可能会抛出异常,这些机器人就会收到 500 错误。请参阅流式渲染指南中的机器人与爬虫,了解这涵盖哪些用户代理以及如何更改该列表。

Next.js 中文网