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,仍可触发重新渲染。
参数#
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:- 只能在 Server Actions 中使用
- 下一个请求等待新数据(不提供旧内容)
- 专为读己之写场景设计
revalidateTag:- 可在 Server Actions 和 Route Handlers 中使用
- 使用
profile="max"(推荐):在后台获取新数据的同时提供缓存数据(stale-while-revalidate) - 使用自定义 profile:可配置为任何缓存生命周期 profile 以满足高级用途
- 不使用 profile:旧版行为,等同于
updateTag
示例#
具有读己之写的 Server Action#
'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}`)
}'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 之外使用时报错#
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 端点
相关#
revalidateTag- 用于在 Route Handlers 中使标签失效revalidatePath- 用于使特定路径失效