Next.js 中的缓存

Next.js 通过缓存渲染工作和数据请求来提升应用程序性能并降低成本。此页面深入介绍了 Next.js 的缓存机制、可用于配置它们的 API 以及它们之间的交互方式。

**需知**：此页面帮助你了解 Next.js 的内部工作原理，但**不是**有效使用 Next.js 的必要知识。Next.js 的大多数缓存启发式算法都由你的 API 使用情况决定，并且具有默认值，可在无需或只需最少配置的情况下实现最佳性能。如果你想直接查看示例，请从这里开始。

概述

以下是不同缓存机制及其用途的概览

默认情况下，Next.js 会尽可能多地缓存以提高性能并降低成本。这意味着路由会被**静态渲染**，并且数据请求会被**缓存**，除非你选择退出。下图显示了默认的缓存行为：在构建时静态渲染路由以及首次访问静态路由时。

缓存行为会根据路由是静态渲染还是动态渲染、数据是缓存还是未缓存以及请求是否属于初始访问或后续导航而有所不同。根据你的用例，你可以为各个路由和数据请求配置缓存行为。

请求记忆化

React 扩展了fetch API 以自动**记忆化**具有相同 URL 和选项的请求。这意味着你可以在 React 组件树中的多个位置调用 fetch 函数以获取相同的数据，而只需执行一次。

例如，如果你需要在整个路由中使用相同的数据（例如，在布局、页面和多个组件中），则无需在树的顶部获取数据，也不需要在组件之间传递 props。相反，你可以在需要它的组件中获取数据，而无需担心跨网络对相同数据发出多个请求的性能影响。

async function getItem() {
  // The `fetch` function is automatically memoized and the result
  // is cached
  const res = await fetch('https://.../item/1')
  return res.json()
}
 
// This function is called twice, but only executed the first time
const item = await getItem() // cache MISS
 
// The second call could be anywhere in your route
const item = await getItem() // cache HIT

请求记忆化工作原理

• 在渲染路由时，首次调用特定请求时，其结果将不在内存中，并且将是缓存MISS。
• 因此，该函数将被执行，数据将从外部源获取，结果将存储在内存中。
• 在同一渲染过程中后续对该请求的函数调用将是缓存HIT，并且数据将从内存中返回，而无需执行该函数。
• 一旦路由已渲染且渲染过程完成，内存将被“重置”，并且所有请求记忆化条目都将被清除。

需知:

• 请求记忆化是 React 的特性，而不是 Next.js 的特性。将其包含在这里是为了展示它如何与其他缓存机制交互。
• 记忆化仅适用于fetch请求中的GET方法。
• 记忆化仅适用于 React 组件树，这意味着
  • 它适用于generateMetadata、generateStaticParams、布局、页面和其他服务器组件中的fetch请求。
  • 它不适用于路由处理程序中的fetch请求，因为它们不是 React 组件树的一部分。
• 对于fetch不适合的情况（例如，某些数据库客户端、CMS 客户端或 GraphQL 客户端），可以使用React cache函数来记忆化函数。

持续时间

缓存持续到服务器请求的生命周期，直到 React 组件树渲染完成。

重新验证

由于记忆化没有在服务器请求之间共享，并且仅在渲染期间应用，因此无需重新验证它。

选择退出

记忆化仅适用于fetch请求中的GET方法，其他方法，例如POST和DELETE，不会被记忆化。此默认行为是 React 的优化，我们不建议选择退出。

要管理单个请求，您可以使用来自signal的AbortController的属性。但是，这不会使请求退出记忆化，而是中止正在进行的请求。

const { signal } = new AbortController()
fetch(url, { signal })

数据缓存

Next.js 具有内置的数据缓存，该缓存持久化数据获取的结果，跨越传入的服务器请求和部署。这之所以成为可能，是因为 Next.js 扩展了原生fetch API，以允许服务器上的每个请求设置其自身的持久缓存语义。

注意：在浏览器中，fetch的cache选项指示请求将如何与浏览器的 HTTP 缓存交互；在 Next.js 中，cache选项指示服务器端请求将如何与服务器的数据缓存交互。

您可以使用fetch的cache和next.revalidate选项来配置缓存行为。

数据缓存的工作原理

• 第一次在渲染期间调用具有'force-cache'选项的fetch请求时，Next.js 会检查数据缓存中是否存在缓存的响应。
• 如果找到缓存的响应，则会立即返回并记忆化。
• 如果找不到缓存的响应，则会向数据源发出请求，将结果存储在数据缓存中，并进行记忆化。
• 对于未缓存的数据（例如，未定义cache选项或使用{ cache: 'no-store' }），始终从数据源获取结果，并进行记忆化。
• 无论数据是否缓存，请求始终都会被记忆化，以避免在 React 渲染过程中对相同数据发出重复请求。

数据缓存和请求记忆化之间的区别

虽然这两种缓存机制都通过重用缓存数据来帮助提高性能，但数据缓存在传入的请求和部署之间是持久的，而记忆化仅持续请求的生命周期。

持续时间

数据缓存在传入的请求和部署之间是持久的，除非您重新验证或选择退出。

重新验证

缓存数据可以通过两种方式重新验证，使用

• 基于时间的重新验证：在经过一定时间后并发出新请求时重新验证数据。这对于不经常更改且新鲜度不是那么关键的数据很有用。
• 按需重新验证：基于事件（例如表单提交）重新验证数据。按需重新验证可以使用基于标签或基于路径的方法来一次重新验证一组数据。当您希望尽快显示最新数据时（例如，当您无头 CMS 中的内容更新时），这很有用。

基于时间的重新验证

要以定时间隔重新验证数据，您可以使用fetch的next.revalidate选项来设置资源的缓存生命周期（以秒为单位）。

// Revalidate at most every hour
fetch('https://...', { next: { revalidate: 3600 } })

或者，您可以使用路由片段配置选项来配置片段中的所有fetch请求，或者在您无法使用fetch的情况下。

基于时间的重新验证的工作原理

• 第一次调用带有revalidate的 fetch 请求时，数据将从外部数据源获取并存储在数据缓存中。
• 在指定的时间范围内（例如 60 秒）内调用的任何请求都将返回缓存的数据。
• 超过该时间范围后，下一个请求仍将返回缓存的（现在已过时）数据。
  • Next.js 将在后台触发数据的重新验证。
  • 成功获取数据后，Next.js 将使用新数据更新数据缓存。
  • 如果后台重新验证失败，则先前的数据将保持不变。

这类似于stale-while-revalidate行为。

按需重新验证

数据可以通过路径(revalidatePath)或缓存标签(revalidateTag)按需重新验证。

按需重新验证的工作原理

• 第一次调用fetch请求时，数据将从外部数据源获取并存储在数据缓存中。
• 当触发按需重新验证时，相应的缓存条目将从缓存中清除。
  • 这与基于时间的重新验证不同，后者会将过时的数据保留在缓存中，直到获取到新数据。
• 下次发出请求时，它将再次是缓存MISS，并且数据将从外部数据源获取并存储在数据缓存中。

选择退出

如果您*不*希望缓存来自fetch的响应，您可以执行以下操作

let data = await fetch('https://api.vercel.app/blog', { cache: 'no-store' })

完整路由缓存

相关术语:

您可能会看到自动静态优化、静态站点生成或静态渲染这些术语被互换使用，以指代在构建时渲染和缓存应用程序路由的过程。

Next.js 会在构建时自动渲染和缓存路由。这是一种优化，允许您提供缓存的路由，而不是在每次请求时都在服务器上渲染，从而加快页面加载速度。

要了解完整路由缓存的工作原理，了解 React 如何处理渲染以及 Next.js 如何缓存结果很有帮助

1. 服务器上的 React 渲染

在服务器上，Next.js 使用 React 的 API 来协调渲染。渲染工作被分成块：按单个路由片段和 Suspense 边界。

每个块分两步渲染

1. React 将服务器组件渲染成一种针对流式传输优化的特殊数据格式，称为React 服务器组件有效负载。
2. Next.js 使用 React 服务器组件有效负载和客户端组件 JavaScript 指令在服务器上渲染HTML。

这意味着我们不必等到所有内容都渲染完毕才能缓存工作或发送响应。相反，我们可以在工作完成时流式传输响应。

什么是 React 服务器组件有效负载？

React 服务器组件有效负载是渲染的 React 服务器组件树的紧凑二进制表示。它由客户端上的 React 用于更新浏览器的 DOM。React 服务器组件有效负载包含

• 服务器组件的渲染结果
• 客户端组件应渲染的位置的占位符，以及对其 JavaScript 文件的引用
• 从服务器组件传递到客户端组件的任何 props

要了解更多信息，请参阅服务器组件文档。

2. 服务器上的 Next.js 缓存（完整路由缓存）

Next.js 的默认行为是在服务器上缓存路由的渲染结果（React 服务器组件有效负载和 HTML）。这适用于构建时的静态渲染路由，或重新验证期间。

3. 客户端上的 React 水合和协调

在客户端请求时

1. HTML 用于立即显示客户端和服务器组件的快速非交互式初始预览。
2. React 服务器组件有效负载用于协调客户端和渲染的服务器组件树，并更新 DOM。
3. JavaScript 指令用于 水合 客户端组件并使应用程序具有交互性。

4. 客户端上的 Next.js 缓存（路由缓存）

React 服务器组件有效负载存储在客户端 路由缓存 中 - 一个独立的内存缓存，按单个路由段划分。此路由缓存用于通过存储先前访问的路由和预取未来的路由来改善导航体验。

5. 后续导航

在后续导航或预取期间，Next.js 将检查 React 服务器组件有效负载是否存储在路由缓存中。如果是，它将跳过向服务器发送新请求。

如果路由段不在缓存中，Next.js 将从服务器获取 React 服务器组件有效负载，并在客户端填充路由缓存。

静态和动态渲染

路由在构建时是否被缓存取决于它是静态渲染还是动态渲染。静态路由默认情况下会被缓存，而动态路由则在请求时渲染，不会被缓存。

此图表显示了静态渲染路由和动态渲染路由之间的区别，以及缓存和未缓存的数据

了解更多关于 静态和动态渲染 的信息。

持续时间

默认情况下，完整路由缓存是持久化的。这意味着渲染输出在用户请求之间被缓存。

失效

您可以通过两种方式使完整路由缓存失效

• 重新验证数据：重新验证 数据缓存 将依次使路由缓存失效，方法是在服务器上重新渲染组件并缓存新的渲染输出。
• 重新部署：与跨部署持久化的数据缓存不同，完整路由缓存在新的部署中会被清除。

选择退出

您可以选择退出完整路由缓存，或者换句话说，为每个传入请求动态渲染组件，方法是

• 使用 动态 API：这将使路由退出完整路由缓存并在请求时动态渲染它。数据缓存仍然可以使用。
• 使用 dynamic = 'force-dynamic' 或 revalidate = 0 路由段配置选项：这将跳过完整路由缓存和数据缓存。这意味着组件将在每个传入请求中被渲染，并且数据将在每个传入请求中被获取到服务器。路由缓存仍然适用，因为它是一个客户端缓存。
• 选择退出 数据缓存：如果路由具有未缓存的 fetch 请求，则这将使路由退出完整路由缓存。特定 fetch 请求的数据将为每个传入请求获取。不会选择退出缓存的其他 fetch 请求仍将缓存在数据缓存中。这允许混合使用缓存和未缓存的数据。

客户端路由缓存

Next.js 具有一个内存中的客户端路由缓存，它存储路由段的 RSC 有效负载，并按布局、加载状态和页面进行划分。

当用户在路由之间导航时，Next.js 会缓存已访问的路由段并 预取 用户可能要导航到的路由。这将导致即时前后导航、导航之间无需完整页面重新加载以及 React 状态和浏览器状态的保留。

使用路由缓存

• 布局在导航时被缓存和重用（部分渲染）。
• 加载状态在导航时被缓存和重用，以实现 即时导航。
• 页面默认情况下不会被缓存，但在浏览器前后导航期间会被重用。您可以通过使用实验性 staleTimes 配置选项来启用页面段的缓存。

需要注意的是：此缓存专门适用于 Next.js 和服务器组件，与浏览器的 bfcache 不同，尽管它具有类似的结果。

持续时间

缓存存储在浏览器的临时内存中。有两个因素决定路由缓存持续的时间

• 会话：缓存在导航之间持续存在。但是，它会在页面刷新时被清除。
• 自动失效期：布局和加载状态的缓存会在特定时间后自动失效。持续时间取决于资源是如何 预取 的，以及资源是否 静态生成 的
  • 默认预取（prefetch={null} 或未指定）：动态页面未缓存，静态页面为 5 分钟。
  • 完整预取（prefetch={true} 或 router.prefetch）：静态和动态页面均为 5 分钟。

虽然页面刷新会清除**所有**缓存的段，但自动失效期仅影响从预取时间起单个段。

需要注意的是：实验性 staleTimes 配置选项可用于调整上述自动失效时间。

失效

您可以通过两种方式使路由缓存失效

• 在服务器操作中
  • 按路径（使用 revalidatePath）或按缓存标签（使用 revalidateTag）按需重新验证数据。
  • 使用 cookies.set 或 cookies.delete 使路由缓存失效，以防止使用 cookie 的路由变得陈旧（例如，身份验证）。
• 调用 router.refresh 将使路由缓存失效并向服务器发出对当前路由的新请求。

选择退出

从 Next.js 15 开始，页面段默认情况下会被选择退出。

需要注意的是：您还可以通过将 <Link> 组件的 prefetch 属性设置为 false 来选择退出 预取。

缓存交互

在配置不同的缓存机制时，了解它们如何相互交互非常重要

数据缓存和完整路由缓存

• 重新验证或选择退出数据缓存**将**使完整路由缓存失效，因为渲染输出取决于数据。
• 使完整路由缓存失效或选择退出完整路由缓存**不会**影响数据缓存。您可以动态渲染具有缓存和未缓存数据的路由。当您的页面大部分使用缓存数据但有一些组件依赖于需要在请求时获取的数据时，这很有用。您可以动态渲染而无需担心重新获取所有数据的性能影响。

数据缓存和客户端路由器缓存

• 要立即使数据缓存和路由器缓存失效，您可以在 revalidatePath 或 revalidateTag 中使用 服务器操作。
• 在 路由处理程序 中重新验证数据缓存**不会**立即使路由器缓存失效，因为路由处理程序未绑定到特定路由。这意味着路由器缓存将继续提供之前的有效负载，直到进行硬刷新或自动失效时间段过去。

API

下表概述了不同的 Next.js API 如何影响缓存

<Link>

默认情况下，<Link> 组件会自动从完整路由缓存中预取路由，并将 React 服务器组件有效负载添加到路由器缓存中。

要禁用预取，您可以将 prefetch 属性设置为 false。但这不会永久跳过缓存，当用户访问路由时，路由段仍将在客户端缓存。

详细了解 <Link> 组件。

router.prefetch

useRouter 钩子的 prefetch 选项可用于手动预取路由。这会将 React 服务器组件有效负载添加到路由器缓存中。

请参阅 useRouter 钩子 API 参考。

router.refresh

useRouter 钩子的 refresh 选项可用于手动刷新路由。这会完全清除路由器缓存，并向服务器发出对当前路由的新请求。refresh 不会影响数据或完整路由缓存。

渲染结果将在客户端进行协调，同时保留 React 状态和浏览器状态。

请参阅 useRouter 钩子 API 参考。

fetch

从 fetch 返回的数据会自动缓存在数据缓存中。

如果您*不*希望缓存来自fetch的响应，您可以执行以下操作

let data = await fetch('https://api.vercel.app/blog', { cache: 'no-store' })

请参阅 fetch API 参考 以获取更多选项。

fetch options.cache

您可以通过将 cache 选项设置为 force-cache 来选择将各个 fetch 缓存。

// Opt into caching
fetch(`https://...`, { cache: 'force-cache' })

请参阅 fetch API 参考 以获取更多选项。

fetch options.next.revalidate

您可以使用 fetch 的 next.revalidate 选项来设置单个 fetch 请求的重新验证周期（以秒为单位）。这将重新验证数据缓存，进而重新验证完整路由缓存。将获取最新数据，并且组件将在服务器上重新渲染。

// Revalidate at most after 1 hour
fetch(`https://...`, { next: { revalidate: 3600 } })

请参阅 fetch API 参考 以获取更多选项。

fetch options.next.tags 和 revalidateTag

Next.js 具有缓存标记系统，用于细粒度的数据缓存和重新验证。

1. 当使用 fetch 或 unstable_cache 时，您可以选择使用一个或多个标签标记缓存条目。
2. 然后，您可以调用 revalidateTag 来清除与该标签关联的缓存条目。

例如，您可以在获取数据时设置标签

// Cache data with a tag
fetch(`https://...`, { next: { tags: ['a', 'b', 'c'] } })

然后，使用标签调用 revalidateTag 来清除缓存条目

// Revalidate entries with a specific tag
revalidateTag('a')

您可以根据要实现的目标在两个地方使用 revalidateTag

1. 路由处理程序 - 响应第三方事件（例如 Webhook）重新验证数据。由于路由处理程序未绑定到特定路由，因此这不会立即使路由器缓存失效。
2. 服务器操作 - 在用户操作（例如表单提交）后重新验证数据。这将使关联路由的路由器缓存失效。

revalidatePath

revalidatePath 允许您手动重新验证数据**并**在单个操作中重新渲染特定路径下方的路由段。调用 revalidatePath 方法会重新验证数据缓存，进而使完整路由缓存失效。

revalidatePath('/')

您可以根据要实现的目标在两个地方使用 revalidatePath

1. 路由处理程序 - 响应第三方事件（例如 Webhook）重新验证数据。
2. 服务器操作 - 在用户交互（例如表单提交、单击按钮）后重新验证数据。

请参阅 revalidatePath API 参考 以获取更多信息。

revalidatePath 与 router.refresh

调用 router.refresh 将清除路由器缓存，并在服务器上重新渲染路由段，而不会使数据缓存或完整路由缓存失效。

不同之处在于 revalidatePath 会清除数据缓存和完整路由缓存，而 router.refresh() 不会更改数据缓存和完整路由缓存，因为它是一个客户端 API。

动态 API

诸如 cookies 和 headers 之类的动态 API 以及 Pages 中的 searchParams 属性依赖于运行时传入的请求信息。使用它们将使路由退出完整路由缓存，换句话说，路由将被动态渲染。

cookies

在服务器操作中使用 cookies.set 或 cookies.delete 会使路由器缓存失效，以防止使用 cookie 的路由变得陈旧（例如，以反映身份验证更改）。

请参阅 cookies API 参考。

分段配置选项

路由片段配置选项可用于覆盖路由片段默认值，或者在您无法使用fetch API 时（例如数据库客户端或第三方库）。

以下路由片段配置选项将选择退出完整路由缓存

• const dynamic = 'force-dynamic'

此配置选项将使所有获取操作退出数据缓存（即no-store）。

• const fetchCache = 'default-no-store'

请参阅fetchCache以查看更多高级选项。

请参阅路由片段配置文档以获取更多选项。

generateStaticParams

对于动态片段（例如app/blog/[slug]/page.js），由generateStaticParams提供的路径在构建时会被缓存到完整路由缓存中。在请求时，Next.js 也会缓存构建时未知的路径，第一次访问时也会缓存这些路径。

要在构建时静态渲染所有路径，请向generateStaticParams提供完整路径列表。

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
 
  return posts.map((post) => ({
    slug: post.slug,
  }))
}

要在构建时静态渲染部分路径，并在运行时第一次访问其余路径时渲染，请返回部分路径列表。

export async function generateStaticParams() {
  const posts = await fetch('https://.../posts').then((res) => res.json())
 
  // Render the first 10 posts at build time
  return posts.slice(0, 10).map((post) => ({
    slug: post.slug,
  }))
}

要在第一次访问时静态渲染所有路径，请返回一个空数组（构建时不会渲染任何路径）或使用export const dynamic = 'force-static'

export async function generateStaticParams() {
  return []
}

注意：即使是空数组，也必须从generateStaticParams返回一个数组。否则，路由将被动态渲染。

export const dynamic = 'force-static'

要禁用请求时的缓存，请在路由片段中添加export const dynamicParams = false选项。使用此配置选项时，仅由generateStaticParams提供的路径会被提供服务，其他路由将返回 404 或匹配（对于通配符路由）。

React cache 函数

React cache 函数允许您记忆函数的返回值，从而允许您多次调用同一个函数，而只执行一次。

由于fetch请求会自动记忆，因此您无需将其包装在React cache中。但是，您可以使用cache手动记忆数据请求，以用于fetch API 不适用的场景。例如，某些数据库客户端、CMS 客户端或 GraphQL 客户端。

import { cache } from 'react'
import db from '@/lib/db'
 
export const getItem = cache(async (id: string) => {
  const item = await db.item.findUnique({ id })
  return item
})