revalidateTag 允许您根据需要，针对特定的缓存标签使缓存数据失效。

此函数非常适合那些可以接受轻微更新延迟的内容，例如博客文章、产品目录或文档。用户会收到陈旧内容，而新鲜数据则在后台加载。

用法

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

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

重验证行为

重验证行为取决于您是否提供了第二个参数：

• 使用 profile="max" (推荐)：标签条目被标记为陈旧，下次访问带有该标签的资源时，它将使用 stale-while-revalidate 语义。这意味着在后台获取新鲜内容的同时，提供陈旧内容。
• 使用自定义缓存生命周期配置文件：对于高级用法，您可以指定应用程序定义的任何缓存生命周期配置文件，从而实现根据您的特定缓存需求量身定制的自定义重验证行为。
• 不带第二个参数 (已弃用)：标签条目会立即过期，对该资源的下一个请求将是阻塞式重验证/缓存未命中。此行为现已弃用，您应该使用 profile="max" 或迁移到 updateTag。

须知：当使用 profile="max" 时，revalidateTag 会将带有标签的数据标记为陈旧，但只有在下次访问使用该标签的页面时才会获取新鲜数据。这意味着调用 revalidateTag 不会立即触发多次重验证。失效只会在下次访问任何使用该标签的页面时发生。

参数

revalidateTag(tag: string, profile: string | { expire?: number }): void;

• tag: 一个字符串，表示您要重验证的数据所关联的缓存标签。不得超过 256 个字符。此值区分大小写。
• profile: 一个字符串，指定重验证行为。推荐值为 "max"，它提供 stale-while-revalidate 语义，或者在 cacheLife 中定义的任何其他默认或自定义配置文件。另外，您可以传递一个带有 expire 属性的对象，以实现自定义过期行为。

标签必须首先分配给缓存数据。您可以通过两种方式进行：

• 将 next.tags 选项与 fetch 一起使用，以缓存外部 API 请求：

fetch(url, { next: { tags: ['posts'] } })

• 在带有 'use cache' 指令的缓存函数或组件内部使用 cacheTag：

import { cacheTag } from 'next/cache'

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

须知：单参数形式 revalidateTag(tag) 已弃用。如果 TypeScript 错误被抑制，它目前仍然有效，但此行为可能会在未来版本中移除。请更新为双参数签名。

返回值

revalidateTag 不返回任何值。

与 revalidatePath 的关系

revalidateTag 使所有使用特定标签的页面中的数据失效，而 revalidatePath 则使特定的页面或布局路径失效。

须知：这些函数有不同的用途，可能需要结合使用以实现全面的数据一致性。有关详细示例和注意事项，请参阅 relationship with revalidateTag and updateTag 以获取更多信息。

示例

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

服务器操作

'use server'

import { revalidateTag } from 'next/cache'

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

'use server'

import { revalidateTag } from 'next/cache'

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

路由处理器

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',
  })
}

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',
  })
}

须知：对于需要立即过期的 webhook 或第三方服务，您可以将 { expire: 0 } 作为第二个参数传递：revalidateTag(tag, { expire: 0 })。当外部系统调用您的 Route Handlers 并要求数据立即过期时，此模式是必需的。对于所有其他情况，建议在 Server Actions 中使用 updateTag 来进行即时更新。