缓存标签 | DevRefinery

cacheTag 函数允许你为缓存数据打上标签，以便进行按需失效。通过将标签与缓存条目关联，你可以有选择地清除或重新验证特定的缓存条目，而不影响其他缓存数据。

使用

要使用 cacheTag，请在你的 next.config.js 文件中启用 cacheComponents 标志：

typescript

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

javascript

const nextConfig = {
  cacheComponents: true,
}

export default nextConfig

cacheTag 函数接受一个或多个字符串值。

tsx

import { cacheTag } from 'next/cache'

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const data = await fetch('/api/data')
  return data
}

jsx

import { cacheTag } from 'next/cache'

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const data = await fetch('/api/data')
  return data
}

然后，你可以在另一个函数中按需清除缓存，例如在路由处理程序或 Server Action 中使用 revalidateTag API：

tsx

'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('my-data')
}

jsx

'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('my-data')
}

须知

幂等标签：多次应用同一个标签没有额外效果。
多个标签：你可以通过向 cacheTag 传入多个字符串值，为单个缓存条目分配多个标签。

tsx

cacheTag('tag-one', 'tag-two')

限制：自定义标签的最大长度为 256 个字符，最大标签项数为 128。

示例

为组件或函数打标签

通过在缓存函数或组件中调用 cacheTag 来标记你的缓存数据：

tsx

import { cacheTag } from 'next/cache'

interface BookingsProps {
  type: string
}

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  cacheTag('bookings-data')

  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }

  return //...
}

jsx

import { cacheTag } from 'next/cache'

export async function Bookings({ type = 'haircut' }) {
  'use cache'
  cacheTag('bookings-data')

  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }

  return //...
}

从外部数据创建标签

你可以使用异步函数返回的数据来标记缓存条目。

tsx

import { cacheTag } from 'next/cache'

interface BookingsProps {
  type: string
}

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  async function getBookingsData() {
    'use cache'
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    cacheTag('bookings-data', data.id)
    return data
  }
  return //...
}

jsx

import { cacheTag } from 'next/cache'

export async function Bookings({ type = 'haircut' }) {
  async function getBookingsData() {
    'use cache'
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    cacheTag('bookings-data', data.id)
    return data
  }
  return //...
}

使带标签的缓存失效

使用 revalidateTag，你可以在需要时使特定标签的缓存失效：

tsx

'use server'

import { revalidateTag } from 'next/cache'

export async function updateBookings() {
  await updateBookingData()
  revalidateTag('bookings-data')
}

jsx

'use server'

import { revalidateTag } from 'next/cache'

export async function updateBookings() {
  await updateBookingData()
  revalidateTag('bookings-data')
}

使用

要使用 cacheTag，请在你的 next.config.js 文件中启用 cacheComponents 标志：

typescript

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

javascript

const nextConfig = {
  cacheComponents: true,
}

export default nextConfig

cacheTag 函数接受一个或多个字符串值。

tsx

import { cacheTag } from 'next/cache'

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const data = await fetch('/api/data')
  return data
}

jsx

import { cacheTag } from 'next/cache'

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const data = await fetch('/api/data')
  return data
}

然后，你可以在另一个函数中按需清除缓存，例如在路由处理程序或 Server Action 中使用 revalidateTag API：

tsx

'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('my-data')
}

jsx

'use server'

import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('my-data')
}

须知

幂等标签：多次应用同一个标签没有额外效果。
多个标签：你可以通过向 cacheTag 传入多个字符串值，为单个缓存条目分配多个标签。

tsx

cacheTag('tag-one', 'tag-two')

限制：自定义标签的最大长度为 256 个字符，最大标签项数为 128。

示例

为组件或函数打标签

通过在缓存函数或组件中调用 cacheTag 来标记你的缓存数据：

tsx

import { cacheTag } from 'next/cache'

interface BookingsProps {
  type: string
}

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  cacheTag('bookings-data')

  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }

  return //...
}

jsx

import { cacheTag } from 'next/cache'

export async function Bookings({ type = 'haircut' }) {
  'use cache'
  cacheTag('bookings-data')

  async function getBookingsData() {
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    return data
  }

  return //...
}

从外部数据创建标签

你可以使用异步函数返回的数据来标记缓存条目。

tsx

import { cacheTag } from 'next/cache'

interface BookingsProps {
  type: string
}

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  async function getBookingsData() {
    'use cache'
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    cacheTag('bookings-data', data.id)
    return data
  }
  return //...
}

jsx

import { cacheTag } from 'next/cache'

export async function Bookings({ type = 'haircut' }) {
  async function getBookingsData() {
    'use cache'
    const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
    cacheTag('bookings-data', data.id)
    return data
  }
  return //...
}

使带标签的缓存失效

使用 revalidateTag，你可以在需要时使特定标签的缓存失效：

tsx

'use server'

import { revalidateTag } from 'next/cache'

export async function updateBookings() {
  await updateBookingData()
  revalidateTag('bookings-data')
}

jsx

'use server'

import { revalidateTag } from 'next/cache'

export async function updateBookings() {
  await updateBookingData()
  revalidateTag('bookings-data')
}

文档导航

使用

须知

示例

为组件或函数打标签

从外部数据创建标签

使带标签的缓存失效

使用

须知

示例

为组件或函数打标签

从外部数据创建标签

使带标签的缓存失效