NNext.js 中文网 GitHub

revalidateTag

revalidateTag 函数的 API 参考。

revalidateTag 允许你按需使特定缓存标签的缓存数据失效。

此函数适用于可以接受更新略有延迟的内容,例如博客文章、产品目录或文档。使用推荐的 max profile 时,用户会收到旧内容,而新数据在后台加载。

用法#

revalidateTag 可以在 Server Functions 和 Route Handlers 中调用。

revalidateTag 不能在 Client Components 或 Proxy 中调用,因为它只能在服务端环境中工作。

重新验证行为#

调用 revalidateTag 会将带有该标签的数据标记为陈旧。下一次对该数据的请求会启动重新验证,并在运行期间使用 stale-while-revalidate 语义提供旧内容。第二个参数设置旧内容可提供的时长。超过该时长后,请求会阻塞直到重新验证完成。

  • profile="max"(推荐):一年窗口,足够长,以便在重新验证运行期间始终向请求提供旧内容。
  • 其他 profile 或对象:当你需要不同的窗口时,可以使用 cacheLife 中定义的任何其他默认或自定义 profile,或带有 expire 属性的对象。
  • { expire: 0 }:永不提供旧内容,因此下一次请求是阻塞式的重新验证/缓存未命中。当调用方需要数据立即消失且无法使用 updateTag 时使用。
  • 无第二个参数(已弃用):行为类似 { expire: 0 }。请在 Server Actions 中迁移到 updateTag,或使用 profile="max"。

profile 设定了超过该点后数据正确性比速度更重要的临界点。

小知识:重新验证由请求触发,而非 revalidateTag 调用,因此使用该标签的页面会在被访问时重新验证,而不是一次性全部重新验证。

对于有多个服务端实例的部署,请参阅分布式标签协调。

客户端缓存行为#

在 Server Action 中,解析为 expire: 0 的 profile 还会触发 updateTag 的客户端刷新和缓存失效。非零的 expire 值(例如 'max')不会触发这些客户端效果。

Route Handler 调用会使服务端缓存数据失效,但不会立即刷新已打开页面的客户端缓存。

参数#

ts
revalidateTag(tag: string, profile: string | { expire?: number }): void;
  • tag:一个字符串,表示与要重新验证的数据关联的缓存标签。标签区分大小写,且不得超过 256 个字符。超过限制的标签永远不会分配给缓存数据,因此重新验证它不会有任何效果。
  • profile:旧内容可提供的时长,请参阅重新验证行为。推荐值为 "max"。也接受 cacheLife 中定义的任何其他默认或自定义 profile,且只读取其 expire。你还可以传递带有 expire 属性的对象,单位为秒。

标签必须先分配给缓存数据。可以通过两种方式实现:

  • 使用 next.tags 选项与 fetch 一起缓存外部 API 请求:
tsx
fetch(url, { next: { tags: ['posts'] } })
  • 在带有 'use cache' 指令的缓存函数或组件中使用 cacheTag:
tsx
import { cacheTag } from 'next/cache'

async function getData() {
  'use cache'
  cacheTag('posts')
  // ...
}

小知识:单参数形式 revalidateTag(tag) 已弃用。目前如果抑制 TypeScript 错误它仍能工作,但此行为可能会在未来版本中移除。请更新为双参数签名。

返回值#

revalidateTag 不返回任何值。

与 revalidatePath 的关系#

revalidateTag 会使所有使用特定标签的页面上的对应数据失效,而 revalidatePath 会使特定的页面或布局路径失效。

小知识:这些函数用途不同,可能需要一起使用以实现全面的数据一致性。有关详细示例和注意事项,请参阅与 revalidateTag 和 updateTag 的关系以了解更多信息。

示例#

以下示例演示如何在不同上下文中使用 revalidateTag。两种情况下,我们都使用 profile="max" 将数据标记为陈旧并使用 stale-while-revalidate 语义,这是大多数用例的推荐做法。

Server Action#

app/actions.ts
'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('posts', 'max')
}
app/actions.js
'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('posts', 'max')
}

Route Handler#

app/api/revalidate/route.ts
import type { NextRequest } from 'next/server'
import { revalidateTag } from 'next/cache'

export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag')

  if (tag) {
    revalidateTag(tag, 'max')
    return Response.json({ revalidated: true, now: Date.now() })
  }

  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing tag to revalidate',
  })
}
app/api/revalidate/route.js
import { revalidateTag } from 'next/cache'

export async function GET(request) {
  const tag = request.nextUrl.searchParams.get('tag')

  if (tag) {
    revalidateTag(tag, 'max')
    return Response.json({ revalidated: true, now: Date.now() })
  }

  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing tag to revalidate',
  })
}

当失效操作来自 Server Action 之外(例如 webhook 或其他服务调用 Route Handler)时,无法使用 updateTag。请传递 { expire: 0 } 以立即使数据过期:

ts
revalidateTag(tag, { expire: 0 })
Next.js 中文网