Menu

updateTag

updateTag 允许你在服务器操作中按需更新特定缓存标签的缓存数据。

此函数专为读取自己的写入场景设计，即用户进行更改（如创建帖子）后，UI 立即显示更改，而不是显示陈旧数据。

使用方法

updateTag 只能在服务器操作中调用。它不能在路由处理程序、客户端组件或任何其他上下文中使用。

如果你需要在路由处理程序或其他上下文中使缓存标签失效，请改用 revalidateTag。

值得注意的是：updateTag 会立即使指定标签的缓存数据过期。下一个请求将等待获取新数据，而不是从缓存中提供陈旧内容，确保用户立即看到他们的更改。

参数

updateTag(tag: string): void;
  • tag：表示与你要更新的数据关联的缓存标签的字符串。不得超过 256 个字符。此值区分大小写。

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

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

返回值

updateTag 不返回任何值。

与 revalidateTag 的区别

虽然 updateTag 和 revalidateTag 都会使缓存数据失效，但它们用于不同的目的：

  • updateTag：

    • 只能在服务器操作中使用
    • 下一个请求等待新数据（不提供陈旧内容）
    • 专为读取自己的写入场景设计

  • revalidateTag：

    • 可以在服务器操作和路由处理程序中使用
    • 使用 profile="max"（推荐）：在后台获取新数据时提供缓存数据（陈旧数据重新验证）
    • 使用自定义 profile：可以配置为任何缓存生命周期配置文件以供高级使用
    • 不使用 profile：等同于 updateTag 的旧版行为

示例

具有读取自己的写入功能的服务器操作

app/actions.ts
TypeScript
'use server'
 
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  const title = formData.get('title')
  const content = formData.get('content')
 
  // 在数据库中创建帖子
  const post = await db.post.create({
    data: { title, content },
  })
 
  // 使缓存标签失效，以便新帖子立即可见
  // 'posts' 标签：影响显示帖子列表的任何页面
  updateTag('posts')
  // 'post-{id}' 标签：影响单个帖子详情页面
  updateTag(`post-${post.id}`)
 
  // 重定向到新帖子 - 用户将看到新数据，而不是缓存数据
  redirect(`/posts/${post.id}`)
}

在服务器操作外使用时的错误

app/api/posts/route.ts
TypeScript
import { updateTag } from 'next/cache'
 
export async function POST() {
  // 这将抛出错误
  updateTag('posts')
  // 错误：updateTag 只能在服务器操作中调用
 
  // 在路由处理程序中请改用 revalidateTag
  revalidateTag('posts', 'max')
}

何时使用 updateTag

在以下情况下使用 updateTag：

  • 你在服务器操作中
  • 你需要立即使缓存失效以实现读取自己的写入
  • 你希望确保下一个请求看到更新的数据

在以下情况下改用 revalidateTag：

  • 你在路由处理程序或其他非操作上下文中
  • 你希望使用陈旧数据重新验证语义
  • 你正在构建用于缓存失效的 webhook 或 API 端点

相关内容