use cache
use cache
指令用于指定组件和/或函数被缓存。它可以在文件顶部使用,表示文件中的所有导出都是可缓存的,或者在函数或组件的顶部内联使用,告知 Next.js 返回值应该被缓存并在后续请求中重复使用。这是一个实验性的 Next.js 功能,而不是像 use client
或 use server
那样的原生 React 功能。
用法
在 next.config.ts
文件中使用 useCache
标志启用对 use cache
指令的支持:
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
useCache: true,
},
}
export default nextConfig
此外,当设置了 dynamicIO
标志时,use cache
指令也会被启用。
然后,你可以在文件、组件或函数级别使用 use cache
指令:
// 文件级别
'use cache'
export default async function Page() {
// ...
}
// 组件级别
export async function MyComponent() {
'use cache'
return <></>
}
// 函数级别
export async function getData() {
'use cache'
const data = await fetch('/api/data')
return data
}
值得注意的是
use cache
是一个实验性的 Next.js 功能,而不是像use client
或use server
那样的原生 React 功能。- 任何传递给缓存函数的可序列化参数(或 props),以及从父作用域读取的任何可序列化值,都将被转换为类似 JSON 的格式,并自动成为缓存键的一部分。
- 任何不可序列化的参数、props 或闭包值在缓存函数内部都将变成不透明的引用,只能被传递而不能被检查或修改。这些不可序列化的值将在请求时被填充,不会成为缓存键的一部分。
- 例如,缓存函数可以接收 JSX 作为
children
prop 并返回<div>{children}</div>
,但它无法内省实际的children
对象。
- 例如,缓存函数可以接收 JSX 作为
- 可缓存函数的返回值也必须是可序列化的。这确保了缓存数据可以正确地存储和检索。
- 使用
use cache
指令的函数不能有任何副作用,例如修改状态、直接操作 DOM 或设置定时器以定期执行代码。 - 如果与部分预渲染一起使用,具有
use cache
的段将作为静态 HTML 外壳的一部分被预渲染。 - 与只支持 JSON 数据的
unstable_cache
不同,use cache
可以缓存 React 可以渲染的任何可序列化数据,包括组件的渲染输出。
示例
使用 use cache
缓存整个路由
要预渲染整个路由,在 layout 和 page 文件的顶部都添加 use cache
。这些段被视为应用程序中的单独入口点,将被独立缓存。
'use cache'
export default function Layout({ children }: { children: ReactNode }) {
return <div>{children}</div>
}
在 page
文件中导入并嵌套的任何组件都将继承 page
的缓存行为。
'use cache'
async function Users() {
const users = await fetch('/api/users')
// 遍历用户
}
export default function Page() {
return (
<main>
<Users />
</main>
)
}
这对于之前使用
export const dynamic = "force-static"
选项的应用程序是推荐的,并将确保整个路由被预渲染。
使用 use cache
缓存组件输出
你可以在组件级别使用 use cache
来缓存该组件内执行的任何获取或计算。当你在应用程序中重用组件时,只要 props 保持相同的结构,它就可以共享相同的缓存条目。
props 会被序列化并成为缓存键的一部分,只要序列化的 props 在每个实例中产生相同的值,缓存条目就会被重用。
export async function Bookings({ type = 'haircut' }: BookingsProps) {
'use cache'
async function getBookingsData() {
const data = await fetch(`/api/bookings?type=${encodeURIComponent(type)}`)
return data
}
return //...
}
interface BookingsProps {
type: string
}
使用 use cache
缓存函数输出
由于你可以将 use cache
添加到任何异步函数,所以你不仅限于缓存组件或路由。你可能想要缓存网络请求、数据库查询或计算一些非常慢的东西。通过将 use cache
添加到包含这类工作的函数,它变得可缓存,并且在重用时,将共享相同的缓存条目。
export async function getData() {
'use cache'
const data = await fetch('/api/data')
return data
}
重新验证
默认情况下,当你使用 use cache
指令时,Next.js 设置了 15 分钟的重新验证周期。Next.js 设置了一个近乎无限的过期时间,这意味着它适合不需要频繁更新的内容。
虽然这个重新验证周期可能对你不期望经常更改的内容很有用,但你可以使用 cacheLife
和 cacheTag
API 来配置缓存行为:
这两个 API 跨客户端和服务器缓存层集成,这意味着你可以在一个地方配置缓存语义,让它们在任何地方应用。
有关更多信息,请参阅 cacheLife
和 cacheTag
文档。
交织
如果你需要将不可序列化的参数传递给可缓存函数,你可以将它们作为 children
传递。这意味着 children
引用可以更改而不影响缓存条目。
export default async function Page() {
const uncachedData = await getData()
return (
<CacheComponent>
<DynamicComponent data={uncachedData} />
</CacheComponent>
)
}
async function CacheComponent({ children }: { children: ReactNode }) {
'use cache'
const cachedData = await fetch('/api/cached-data')
return (
<div>
<PrerenderedComponent data={cachedData} />
{children}
</div>
)
}
你还可以通过缓存组件将服务器操作传递给客户端组件,而无需在可缓存函数内调用它们。
import ClientComponent from './ClientComponent'
export default async function Page() {
const performUpdate = async () => {
'use server'
// 执行一些服务器端更新
await db.update(...)
}
return <CacheComponent performUpdate={performUpdate} />
}
async function CachedComponent({
performUpdate,
}: {
performUpdate: () => Promise<void>
}) {
'use cache'
// 不要在这里调用 performUpdate
return <ClientComponent action={performUpdate} />
}
'use client'
export default function ClientComponent({
action,
}: {
action: () => Promise<void>
}) {
return <button onClick={action}>Update</button>
}