Next.js 中文网

主题

updateTag ​

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

¥updateTag allows you to update cached data on-demand for a specific cache tag from within Server Actions.

此函数专为用户可读写的场景而设计，即用户进行更改（例如创建帖子）后，用户界面会立即显示更改后的数据，而不是显示过时的数据。

¥This function is designed for read-your-own-writes scenarios, where a user makes a change (like creating a post), and the UI immediately shows the change, rather than stale data.

用法 ​

¥Usage

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

¥updateTag can only be called from within Server Actions. It cannot be used in Route Handlers, Client Components, or any other context.

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

¥If you need to invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead.

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

¥Good to know: updateTag immediately expires the cached data for the specified tag. The next request will wait to fetch fresh data rather than serving stale content from the cache, ensuring users see their changes immediately.

参数 ​

¥Parameters

tsx
updateTag(tag: string): void;

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

    ¥tag: A string representing the cache tag associated with the data you want to update. Must not exceed 256 characters. This value is case-sensitive.

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

¥Tags must first be assigned to cached data. You can do this in two ways:

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

    ¥Using the next.tags option with fetch for caching external API requests:

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

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

    ¥Using cacheTag inside cached functions or components with the 'use cache' directive:

tsx
import { cacheTag } from 'next/cache'

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

返回 ​

¥Returns

updateTag 不返回值。

¥updateTag does not return a value.

与 revalidateTag 的区别 ​

¥Differences from revalidateTag

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

¥While both updateTag and revalidateTag invalidate cached data, they serve different purposes:

  • updateTag：

    • 仅可用于服务器操作。

      ¥Can only be used in Server Actions

    • 下一个请求等待新数据（不提供过期内容）

      ¥Next request waits for fresh data (no stale content served)

    • 专为读写场景设计

      ¥Designed for read-your-own-writes scenarios

  • revalidateTag：

    • 可用于服务器操作和路由处理程序。

      ¥Can be used in Server Actions and Route Handlers

    • 使用 profile="max"（推荐）：在后台获取新数据的同时提供缓存数据（重新验证时使用缓存数据）。

      ¥With profile="max" (recommended): Serves cached data while fetching fresh data in the background (stale-while-revalidate)

    • 使用自定义配置文件：可配置为任何缓存生命周期配置文件，以实现高级用法。

      ¥With custom profile: Can be configured to any cache life profile for advanced usage

    • 不使用配置文件：与 updateTag 等效的旧版行为

      ¥Without profile: legacy behavior which is equivalent to updateTag

示例 ​

¥Examples

带有自读自写权限的服务器操作 ​

¥Server Action with Read-Your-Own-Writes

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

  // 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}`)
}

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

¥Error when used outside Server Actions

ts
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 ​

¥When to use updateTag

在以下情况下使用 updateTag：

¥Use updateTag when:

  • 你位于服务器操作中

    ¥You're in a Server Action

  • 对于读写操作，你需要立即使缓存失效。

    ¥You need immediate cache invalidation for read-your-own-writes

  • 你希望确保下一个请求能够获取更新后的数据

    ¥You want to ensure the next request sees updated data

在以下情况下使用 revalidateTag：

¥Use revalidateTag instead when:

  • 你位于路由处理程序或其他非操作上下文中

    ¥You're in a Route Handler or other non-action context

  • 你需要使用“过期后重新验证”语义

    ¥You want stale-while-revalidate semantics

  • 你正在构建用于缓存失效的 Webhook 或 API 端点

    ¥You're building a webhook or API endpoint for cache invalidation

¥Related