NNext.js 中文网 GitHub

unstable_cache

unstable_cache 函数的 API 参考。

注意: 在大多数用例中,use cache 在 Next.js 16 中取代了该 API。我们建议选择启用 Cache Components 并迁移到 use cache 指令。

对于必须跨部署持久化的非 fetch 数据,请继续使用 unstable_cache。来自 use cache 和 use cache: remote 的缓存条目不会延续到新部署,因为它们的缓存键包含构建 ID 或 deploymentId。

unstable_cache 允许你缓存高开销操作(如数据库查询)的结果,并在多个请求之间复用。

jsx
import { getUser } from './data';
import { unstable_cache } from 'next/cache';

const getCachedUser = unstable_cache(
  async (id) => getUser(id),
  ['my-app-user']
);

export default async function Component({ userID }) {
  const user = await getCachedUser(userID);
  ...
}

小知识:

  • 不支持在缓存作用域内访问 headers 或 cookies 等请求数据。请在缓存函数外部读取数据,并将所需的值作为参数传入。
  • 该 API 使用 Next.js 的内置缓存来跨请求和跨部署持久化结果。请参阅缓存与重新验证。

不受支持的操作#

传递给 unstable_cache 的函数不能依赖传入的请求。请在调用缓存函数之前从 cookies() 或 headers() 读取值,然后将这些值作为参数传入,使它们成为缓存键的一部分。

缓存函数还不能:

  • 调用 connection(),因为它需要传入的请求
  • 启用或禁用草稿模式
  • 在缓存执行期间调用 revalidateTag()、updateTag() 或 revalidatePath()
  • 调用使用 use cache: private 指令的函数

请在调用缓存函数之前完成依赖请求的工作。变更和重新验证请在之后通过 Server Action 或 Route Handler 执行。

参数#

jsx
const data = unstable_cache(fetchData, keyParts, options)()
  • fetchData:这是一个异步函数,用于获取你要缓存的数据。它必须是一个返回 Promise 的函数。
  • keyParts:这是一个额外的键数组,用于进一步标识缓存。默认情况下,unstable_cache 已经使用函数的参数和字符串化版本作为缓存键。在大多数情况下它是可选的;只有在你使用外部变量而没有将其作为参数传递时才需要使用它。不过,如果没有将闭包作为参数传入,请务必把函数内部使用的闭包添加进来。
  • options:这是一个控制缓存行为的对象。它可以包含以下属性:
    • tags:可用于控制缓存失效的标签数组。Next.js 不会用它来唯一标识该函数。
    • revalidate:缓存重新验证之前的秒数。省略或传入 false 表示无限期缓存,直到调用相应的 revalidateTag() 或 revalidatePath() 方法。

返回值#

unstable_cache 返回一个函数,调用该函数会返回一个解析为缓存数据的 Promise。如果数据不在缓存中,则会调用提供的函数,并将其结果缓存后返回。

示例#

app/page.tsx
import { unstable_cache } from 'next/cache'

export default async function Page({
  params,
}: {
  params: Promise<{ userId: string }>
}) {
  const { userId } = await params
  const getCachedUser = unstable_cache(
    async () => {
      return { id: userId }
    },
    [userId], // 将用户 ID 添加到缓存键
    {
      tags: ['users'],
      revalidate: 60,
    }
  )

  //...
}
app/page.jsx
import { unstable_cache } from 'next/cache'

export default async function Page({ params }) {
  const { userId } = await params
  const getCachedUser = unstable_cache(
    async () => {
      return { id: userId }
    },
    [userId], // 将用户 ID 添加到缓存键
    {
      tags: ['users'],
      revalidate: 60,
    }
  )

  //...
}

版本历史#

版本变更
v14.0.0引入 unstable_cache。
Next.js 中文网