Menu

unstable_cache

在版本 15 中,我们建议使用 use cache 指令来替代。

unstable_cache 允许你缓存昂贵操作(如数据库查询)的结果,并在多个请求之间重复使用它们。

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);
  ...
}

值得注意的是

  • 在缓存作用域内访问动态数据源(如 headerscookies)是不支持的。如果你需要在缓存函数内使用这些数据,请在缓存函数外部使用 headers,并将所需的动态数据作为参数传入。
  • 这个 API 使用 Next.js 内置的 数据缓存 来在请求和部署之间持久化结果。

警告:这个 API 是不稳定的,将来可能会发生变化。随着这个 API 的稳定,如果需要,我们将提供迁移文档和代码修改工具。

参数

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
TypeScript
import { unstable_cache } from 'next/cache'
 
export default async function Page({ params }: { params: { userId: string } }) {
  const getCachedUser = unstable_cache(
    async () => {
      return { id: params.userId }
    },
    [params.userId], // 将用户 ID 添加到缓存键中
    {
      tags: ['users'],
      revalidate: 60,
    }
  )
 
  //...
}

版本历史

版本变更
v14.0.0引入 unstable_cache