NNext.js 中文网 GitHub

updateTag

updateTag 函数的 API 参考。

updateTag 允许你在 Server Actions 中按需更新特定缓存标签的缓存数据。

此函数专为读己之写(read-your-own-writes)场景设计,即用户进行更改(如创建帖子)后,UI 立即显示该更改,而不是旧数据。

用法#

updateTag 只能在 Server Actions 中调用。它不能在 Route Handlers、Client Components 或任何其他上下文中使用。

如果你需要在 Route Handlers 或其他上下文中使缓存标签失效,请改用 revalidateTag。

小知识:updateTag 会立即让指定标签的缓存数据过期。下一个请求将等待获取新数据,而不是从缓存中提供旧内容,从而确保用户立即看到他们的更改。

客户端缓存行为#

当 Server Action 调用 updateTag 时,Next.js 会重新渲染当前路由,并在 action 的响应中发送更新后的 UI,无论该路由是否使用该标签。未缓存的数据会被重新获取,而没有该标签的服务端缓存数据会被重用。

客户端使用 action 的响应重新渲染当前路由,并清除所有预取路由以及为前进/后退导航保留的路由数据,而不仅仅是使用该标签的路由。因此,符合条件的可见链接可能会再次预取。由 Activity 保留的页面保持挂载并保留其 React 状态。当你导航回这些页面时,其服务端数据会刷新。

revalidateTag 的 profile 解析为 expire: 0 时,在 Server Action 中具有相同的效果。这包括 { expire: 0 }、带有 expire: 0 的命名 profile,以及已弃用的单参数形式。使用非零的 expire(如 'max')时,它会将带标签的数据标记为旧数据,并跳过重新渲染和客户端缓存清除。action 中的其他调用,如 refresh,仍可触发重新渲染。

参数#

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

必须先将标签分配给缓存数据。你可以通过两种方式执行此操作:

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

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

返回值#

updateTag 不返回任何值。

与 revalidateTag 的区别#

虽然 updateTag 和 revalidateTag 都会使缓存数据失效,但它们的用途不同:

  • updateTag:
    • 只能在 Server Actions 中使用
    • 下一个请求等待新数据(不提供旧内容)
    • 专为读己之写场景设计
  • revalidateTag:
    • 可在 Server Actions 和 Route Handlers 中使用
    • 使用 profile="max"(推荐):在后台获取新数据的同时提供缓存数据(stale-while-revalidate)
    • 使用自定义 profile:可配置为任何缓存生命周期 profile 以满足高级用途
    • 不使用 profile:旧版行为,等同于 updateTag

示例#

具有读己之写的 Server Action#

app/actions.ts
'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/actions.js
'use server'

import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'

export async function createPost(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}`)
}

在 Server Actions 之外使用时报错#

app/api/posts/route.ts
import { revalidateTag, updateTag } from 'next/cache'

export async function POST() {
  // 这将抛出错误
  updateTag('posts')
  // 错误:updateTag 只能在 Server Action 中调用

  // 在 Route Handlers 中改用 revalidateTag
  revalidateTag('posts', 'max')
}

何时使用 updateTag#

在以下情况下使用 updateTag:

  • 你在 Server Action 中
  • 你需要为读己之写立即失效缓存
  • 你希望确保下一个请求看到更新后的数据

在以下情况下改用 revalidateTag:

  • 你在 Route Handler 或其他非 action 上下文中
  • 你需要 stale-while-revalidate 语义
  • 你正在构建用于缓存失效的 webhook 或 API 端点

相关#

Next.js 中文网