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。 |