updateTag

updateTag 允许您在 Server Actions 中，根据需要更新特定缓存标签的缓存数据。

此函数专为读取自己写入的数据 (read-your-own-writes) 场景设计，即用户进行更改（例如创建帖子）后，用户界面会立即显示该更改，而不是过时的数据。

用法

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

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

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

参数

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 中使用
- 下一个请求等待获取最新数据（不提供过时内容）
- 专为读取自己写入的数据 (read-your-own-writes) 场景设计
revalidateTag：
- 可以在 Server Actions 和 Route Handlers 中使用
- 配合 profile="max"（推荐）：在后台获取最新数据时提供缓存数据（stale-while-revalidate，即陈旧时重新验证）
- 配合自定义配置文件：可以配置为任何缓存生命周期配置文件以进行高级使用
- 不带配置文件：旧版行为，等同于 updateTag

示例

带有读取自己写入的数据 (Read-Your-Own-Writes) 功能的 Server Action

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

  // Create the post in your database
  const post = await db.post.create({
    data: { title, content },
  })

  // Invalidate cache tags so the new post is immediately visible
  // 'posts' tag: affects any page that displays a list of posts
  updateTag('posts')
  // 'post-{id}' tag: affects the individual post detail page
  updateTag(`post-${post.id}`)

  // Redirect to the new post - user will see fresh data, not cached
  redirect(`/posts/${post.id}`)
}

javascript

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

  // Create the post in your database
  const post = await db.post.create({
    data: { title, content },
  })

  // Invalidate cache tags so the new post is immediately visible
  // 'posts' tag: affects any page that displays a list of posts
  updateTag('posts')
  // 'post-{id}' tag: affects the individual post detail page
  updateTag(`post-${post.id}`)

  // Redirect to the new post - user will see fresh data, not cached
  redirect(`/posts/${post.id}`)
}

在 Server Actions 外部使用时出错

typescript

import { updateTag } from 'next/cache'

export async function POST() {
  // This will throw an error
  updateTag('posts')
  // Error: updateTag can only be called from within a Server Action

  // Use revalidateTag instead in Route Handlers
  revalidateTag('posts', 'max')
}

何时使用 updateTag

在以下情况使用 updateTag：

您正在 Server Action 中
您需要立即使缓存失效以实现读取自己写入的数据 (read-your-own-writes)
您希望确保下一个请求看到已更新的数据

在以下情况改用 revalidateTag：

您在 Route Handler 或其他非 Action 上下文中
您希望使用 stale-while-revalidate 语义
您正在构建用于缓存失效的 webhook 或 API 端点

用法

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

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

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

参数

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 中使用
- 下一个请求等待获取最新数据（不提供过时内容）
- 专为读取自己写入的数据 (read-your-own-writes) 场景设计
revalidateTag：
- 可以在 Server Actions 和 Route Handlers 中使用
- 配合 profile="max"（推荐）：在后台获取最新数据时提供缓存数据（stale-while-revalidate，即陈旧时重新验证）
- 配合自定义配置文件：可以配置为任何缓存生命周期配置文件以进行高级使用
- 不带配置文件：旧版行为，等同于 updateTag

示例

带有读取自己写入的数据 (Read-Your-Own-Writes) 功能的 Server Action

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

  // Create the post in your database
  const post = await db.post.create({
    data: { title, content },
  })

  // Invalidate cache tags so the new post is immediately visible
  // 'posts' tag: affects any page that displays a list of posts
  updateTag('posts')
  // 'post-{id}' tag: affects the individual post detail page
  updateTag(`post-${post.id}`)

  // Redirect to the new post - user will see fresh data, not cached
  redirect(`/posts/${post.id}`)
}

javascript

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

  // Create the post in your database
  const post = await db.post.create({
    data: { title, content },
  })

  // Invalidate cache tags so the new post is immediately visible
  // 'posts' tag: affects any page that displays a list of posts
  updateTag('posts')
  // 'post-{id}' tag: affects the individual post detail page
  updateTag(`post-${post.id}`)

  // Redirect to the new post - user will see fresh data, not cached
  redirect(`/posts/${post.id}`)
}

在 Server Actions 外部使用时出错

typescript

import { updateTag } from 'next/cache'

export async function POST() {
  // This will throw an error
  updateTag('posts')
  // Error: updateTag can only be called from within a Server Action

  // Use revalidateTag instead in Route Handlers
  revalidateTag('posts', 'max')
}

何时使用 updateTag

在以下情况使用 updateTag：

您正在 Server Action 中
您需要立即使缓存失效以实现读取自己写入的数据 (read-your-own-writes)
您希望确保下一个请求看到已更新的数据

在以下情况改用 revalidateTag：

您在 Route Handler 或其他非 Action 上下文中
您希望使用 stale-while-revalidate 语义
您正在构建用于缓存失效的 webhook 或 API 端点

文档导航

用法

参数

返回值

与 revalidateTag 的区别

示例

带有读取自己写入的数据 (Read-Your-Own-Writes) 功能的 Server Action

在 Server Actions 外部使用时出错

何时使用 updateTag

相关

用法

参数

返回值

与 revalidateTag 的区别

示例

带有读取自己写入的数据 (Read-Your-Own-Writes) 功能的 Server Action

在 Server Actions 外部使用时出错

何时使用 updateTag

相关