缓存
了解如何在 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 配置文件中:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
}
export default nextConfig/** @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 后,
GETRoute Handlers 遵循与页面相同的预渲染模型。有关详情,请参阅使用 Cache Components 的 Route Handlers。
用法#
use cache 指令会缓存异步函数和组件的返回值。你可以在两个层级上应用它:
- 数据层级:缓存获取或计算数据的函数(例如
getProducts()、getUser(id)) - UI 层级:缓存整个组件或页面(例如
async function BlogPosts())
缓存指令为结果赋予一个生命周期,Next.js 将其用于基于时间的重新验证和渲染优化。关于变更后的按需重新验证,请参阅重新验证。关于缓存结果如何成为静态外壳的一部分并可能被包含在预取中,请参阅预渲染。
小知识: 我们建议将每个缓存指令与
cacheLife搭配使用。如果不搭配,则会应用隐式的default配置。
参数以及从父作用域捕获的任何值都会自动成为缓存键的一部分,这意味着不同的输入会产生不同的缓存条目。关于条目包含的内容,请参阅缓存输出;关于哪些内容可以缓存以及参数如何工作的详细信息,请参阅序列化要求与约束。
数据层级缓存#
要缓存获取数据的异步函数,请在函数体顶部添加 use cache 指令:
import { cacheLife } from 'next/cache'
export async function getUsers() {
'use cache'
cacheLife('hours')
return db.query('SELECT * FROM users')
}当相同的数据被多个组件使用,或你希望将数据与 UI 分开缓存时,数据层级缓存非常有用。
UI 层级缓存#
要缓存整个组件、页面或布局,请在组件或页面主体顶部添加 use cache 指令:
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 会随预渲染外壳一起交付,而异步工作在请求时运行。
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 需要只有在用户发起请求时才可用的信息。这些包括:
cookies- 用户的 cookie 数据headers- 请求头searchParams- URL 查询参数params- 动态路由参数。使用generateStaticParams在构建时预渲染特定值,或使用结合 Cache Components 的 ISR 来提供 App Shell,同时在后台解析未知参数。
访问运行时 API 的组件应包裹在 <Suspense> 中:
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 中提取值,并将它们作为参数传递给缓存函数:
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 窗口内将其视为最新。
静态、缓存与流式#
下面是一个完整的示例,展示静态内容、缓存的动态内容和流式动态内容如何在同一个页面上协同工作:
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> 中:
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>
)
}或者,你可以缓存结果,这样所有用户都会看到相同的值,直到重新验证:
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 的一部分。
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 中。如果数据依赖传入的请求或预期会随时间变化,请在请求时渲染期间读取它。
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 的布局:
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 向下传递,并在那里等待:
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 的搜索页面为例:
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 错误。请参阅流式渲染指南中的机器人与爬虫,了解这涵盖哪些用户代理以及如何更改该列表。