重新验证
了解如何使用基于时间和按需的策略重新验证缓存数据。
本页介绍使用 Cache Components 进行重新验证,可通过在
next.config.ts文件中设置cacheComponents: true来启用。如果你没有使用 Cache Components,请参阅缓存和重新验证(旧模型)指南。
重新验证是更新缓存数据的过程。它让你在继续提供快速缓存响应的同时,确保内容保持新鲜。有两种策略:
- 基于时间的重新验证:使用
cacheLife在设定时长后自动刷新缓存数据。 - 按需重新验证:在数据变更后使用
revalidateTag、updateTag或revalidatePath手动使缓存数据失效。
cacheLife#
cacheLife 控制缓存数据保持有效的时间。在 use cache 作用域内使用它来设置缓存的生命周期。
import { cacheLife } from 'next/cache'
export async function getProducts() {
'use cache'
cacheLife('hours')
return db.query('SELECT * FROM products')
}cacheLife 接受一个预设名称或自定义配置对象:
| 预设 | stale | revalidate | expire |
|---|---|---|---|
default | 5m | 15m | 永不 |
seconds | 30s | 1s | 60s |
minutes | 5m | 1m | 1h |
hours | 5m | 1h | 1d |
days | 5m | 1d | 1w |
weeks | 5m | 1w | 30d |
max | 5m | 30d | 1y |
要进行精细控制,可以传入一个对象:
'use cache'
cacheLife({
stale: 3600, // 1 小时后被视为陈旧
revalidate: 7200, // 2 小时后重新验证
expire: 86400, // 1 天后过期
})小知识: 当缓存使用
seconds预设、revalidate: 0或expire小于 5 分钟时,被视为"短生命周期"。短生命周期缓存会自动从预渲染中排除,转而成为动态空洞。有关详情,请参阅预渲染行为。
有关所有预设和自定义配置选项,请参阅 cacheLife API 参考。
cacheTag#
cacheTag 让你可以为缓存数据添加标签,以便按需使其失效。在 use cache 作用域内使用它:
import { cacheTag } from 'next/cache'
export async function getProducts() {
'use cache'
cacheTag('products')
return db.query('SELECT * FROM products')
}import { cacheTag } from 'next/cache'
export async function getProducts() {
'use cache'
cacheTag('products')
return db.query('SELECT * FROM products')
}添加标签后,使用 revalidateTag 或 updateTag 使缓存失效。
有关更多信息,请参阅 cacheTag API 参考。
revalidateTag#
使用推荐的 'max' 预设时,revalidateTag 会采用 stale-while-revalidate(陈旧即重新验证)语义按标签使缓存条目失效。陈旧内容会立即提供,而新内容在后台加载。这非常适合可以接受更新稍有延迟的内容,例如博客文章或产品目录。
import { revalidateTag } from 'next/cache'
export async function updateUser(id: string) {
// 变更数据
revalidateTag('user', 'max') // 推荐:stale-while-revalidate
}import { revalidateTag } from 'next/cache'
export async function updateUser(id) {
// 变更数据
revalidateTag('user', 'max') // 推荐:stale-while-revalidate
}你可以在多个函数中重复使用同一个标签,一次性对它们全部重新验证。在 Server Action 或 Route Handler 中调用 revalidateTag。
小知识: 第二个参数设置在新内容于后台生成期间,陈旧内容可以被提供多长时间。一旦过期,后续请求将阻塞,直到新内容就绪。使用
'max'可获得最长的陈旧窗口。
有关更多信息,请参阅 revalidateTag API 参考。
updateTag#
updateTag 会立即使缓存数据过期,适用于"读己之写"场景——用户能立即看到自己的更改,而不是陈旧内容。与 revalidateTag 不同,它只能在 Server Actions 中使用。
小知识:
updateTag还会刷新调用它的路由,并使客户端缓存条目失效。有关作用范围及与revalidateTag的比较,请参阅客户端缓存行为。
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
const post = await db.post.create({
data: {
title: formData.get('title'),
content: formData.get('content'),
},
})
updateTag('posts')
redirect(`/posts/${post.id}`)
}import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData) {
const post = await db.post.create({
data: {
title: formData.get('title'),
content: formData.get('content'),
},
})
updateTag('posts')
redirect(`/posts/${post.id}`)
}updateTag | revalidateTag(tag, 'max') | |
|---|---|---|
| 位置 | 仅限 Server Actions | Server Actions 和 Route Handlers |
| 行为 | 立即使缓存过期 | 陈旧即重新验证 |
| 用例 | 读己之写(用户立即看到自己的更改) | 后台刷新(可接受轻微延迟) |
有关更多信息,请参阅 updateTag API 参考。
revalidatePath#
revalidatePath 会使特定路由路径的所有缓存数据失效。当你想重新验证某个路由,但不知道它关联了哪些标签时,可以使用它。
import { revalidatePath } from 'next/cache'
export async function updateUser(id: string) {
// 变更数据
revalidatePath('/profile')
}import { revalidatePath } from 'next/cache'
export async function updateUser(id) {
// 变更数据
revalidatePath('/profile')
}小知识: 尽可能优先使用基于标签的重新验证(
revalidateTag/updateTag),而不是基于路径的重新验证。标签能更精准地定位服务端缓存数据,避免过度失效。客户端缓存失效的作用范围更广。
有关更多信息,请参阅 revalidatePath API 参考。
应该缓存什么?#
缓存那些不依赖运行时数据、且你愿意在一段时间内从缓存中提供的数据。使用 use cache 配合 cacheLife 来描述这种行为。
当内容不需要基于时间的重新验证时(例如来自 CMS 的数据),使用 cacheTag 和一个较长的 cacheLife(如 max)将其保留在静态壳中。将内容源配置为在内容变化时触发 webhook 或其他通知,调用 revalidateTag。这可以减少对未变化内容进行不必要的基于时间的重新验证。
小知识: 在无服务器环境中,内存中的缓存条目可能无法在一次次重新验证之间持久保存。有关详情,请参阅运行时缓存注意事项。