NNext.js 中文网 GitHub

重新验证

了解如何使用基于时间和按需的策略重新验证缓存数据。

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

重新验证是更新缓存数据的过程。它让你在继续提供快速缓存响应的同时,确保内容保持新鲜。有两种策略:

cacheLife#

cacheLife 控制缓存数据保持有效的时间。在 use cache 作用域内使用它来设置缓存的生命周期。

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

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

cacheLife 接受一个预设名称或自定义配置对象:

预设stalerevalidateexpire
default5m15m永不
seconds30s1s60s
minutes5m1m1h
hours5m1h1d
days5m1d1w
weeks5m1w30d
max5m30d1y

要进行精细控制,可以传入一个对象:

tsx
'use cache'
cacheLife({
  stale: 3600, // 1 小时后被视为陈旧
  revalidate: 7200, // 2 小时后重新验证
  expire: 86400, // 1 天后过期
})

小知识: 当缓存使用 seconds 预设、revalidate: 0 或 expire 小于 5 分钟时,被视为"短生命周期"。短生命周期缓存会自动从预渲染中排除,转而成为动态空洞。有关详情,请参阅预渲染行为。

有关所有预设和自定义配置选项,请参阅 cacheLife API 参考。

cacheTag#

cacheTag 让你可以为缓存数据添加标签,以便按需使其失效。在 use cache 作用域内使用它:

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

export async function getProducts() {
  'use cache'
  cacheTag('products')
  return db.query('SELECT * FROM products')
}
app/lib/data.js
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(陈旧即重新验证)语义按标签使缓存条目失效。陈旧内容会立即提供,而新内容在后台加载。这非常适合可以接受更新稍有延迟的内容,例如博客文章或产品目录。

app/lib/actions.ts
import { revalidateTag } from 'next/cache'

export async function updateUser(id: string) {
  // 变更数据
  revalidateTag('user', 'max') // 推荐:stale-while-revalidate
}
app/lib/actions.js
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 的比较,请参阅客户端缓存行为。

app/lib/actions.ts
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}`)
}
app/lib/actions.js
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}`)
}
updateTagrevalidateTag(tag, 'max')
位置仅限 Server ActionsServer Actions 和 Route Handlers
行为立即使缓存过期陈旧即重新验证
用例读己之写(用户立即看到自己的更改)后台刷新(可接受轻微延迟)

有关更多信息,请参阅 updateTag API 参考。

revalidatePath#

revalidatePath 会使特定路由路径的所有缓存数据失效。当你想重新验证某个路由,但不知道它关联了哪些标签时,可以使用它。

app/lib/actions.ts
import { revalidatePath } from 'next/cache'

export async function updateUser(id: string) {
  // 变更数据
  revalidatePath('/profile')
}
app/lib/actions.js
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。这可以减少对未变化内容进行不必要的基于时间的重新验证。

小知识: 在无服务器环境中,内存中的缓存条目可能无法在一次次重新验证之间持久保存。有关详情,请参阅运行时缓存注意事项。

Next.js 中文网