自定义 Next.js 缓存处理器
配置用于存储和重新验证数据的 Next.js 缓存,使其使用 Redis、Memcached 或其他任何外部服务。
如果你想将缓存的页面和数据持久化到持久存储,或在 Next.js 应用程序的多个容器或实例之间共享缓存,可以配置 Next.js 缓存位置。
小知识:
cacheHandler(单数)配置由 Next.js 专门用于服务端缓存操作,例如存储和重新验证 ISR、Route Handler 响应以及优化后的图片。它不用于'use cache'指令。对于'use cache'指令,请改用cacheHandlers(复数)。cacheMaxMemorySize与两者都不同,它分别设置各自的内存缓存大小。
module.exports = {
cacheHandler: require.resolve('./cache-handler.js'),
cacheMaxMemorySize: 0, // 禁用默认的内存缓存
}请参阅 Redis cacheHandler 示例了解可运行的实现,并参阅配置缓存了解由共享存储支持的处理器需要满足哪些条件。
API 参考#
缓存处理器可以实现以下方法:get、set、revalidateTag 和 resetRequestCache。
get()#
| 参数 | 类型 | 描述 |
|---|---|---|
key | string | 缓存值的键。 |
ctx | object | 包含缓存条目种类的上下文。 |
ctx 参数包含一个 kind 属性,指示正在检索的缓存条目的类型。可能的值包括 'APP_PAGE'、'APP_ROUTE'、'PAGES'、'FETCH' 和 'IMAGE'。
缓存键是不透明的标识符。读取和写入条目时请保留完整的键;键不是请求路径名。
响应键包含响应种类以及源路由的 SHA-256 哈希,以防止不同路由共享条目。Pages Router 的源使用路由定义的规范化 pathname,因此索引模块在两种打包工具中具有相同的标识。App Router 的源使用完整的 page 模块名称,包括路由组和并行插槽。例如,由 /blog/[slug] 生成的 /blog/post 的 Pages Router 响应使用 /route-cache/PAGES/<route-hash>/$/blog/post,其中 <route-hash> 是 UTF-8 源字符串 /blog/[slug] 的 64 字符十六进制 SHA-256 摘要。这限制了增加的目录深度,并避免在磁盘上展开 Unicode 源名称。请求路径名仍可读;但无法从其哈希中恢复源路由。此前将键解释为路径名的处理器必须考虑这一命名空间。Fetch 缓存键保持不变。
没有构建适配器时,预渲染响应仍保留在其历史路径 server/pages 和 server/app 中。它们的元数据标识了产生每个不可变构建种子的确切作用域键、源所有者以及回退状态。内置的文件系统缓存会在读取历史种子前校验这些元数据,然后将完整响应提升到 server/route-cache,同时保留原始产物及其存在时间。当配置了适配器后,构建时的响应产物会直接写入其作用域内的 server/route-cache 键,这样在适配器打包之前,发生冲突的路由就无法相互覆盖。静态 output: 'export' 仍会生成普通的公开导出文件。运行时的读写只使用作用域键。自定义缓存处理器接收不透明的作用域键,绝不会用历史路径名查询;外部响应缓存必须原样保留该键。
运行时打包必须保留预渲染清单中现有的源路由元数据。Next.js 还使用它来校验所选路由的允许参数和渲染模式。
在调用 Next.js 之前读取缓存响应的集成,在选择条目时也必须保留源路由所有权。移除路由命名空间或退回到仅限路径名的缓存条目,都会破坏这种隔离。
返回缓存值,如果未找到则返回 null。
set()#
| 参数 | 类型 | 描述 |
|---|---|---|
key | string | 用于存储数据的键。 |
data | Data 或 null | 要缓存的数据。 |
ctx | { tags: [] } | 提供的缓存标签。 |
data 对象包含一个 kind 属性,指示缓存条目的类型。对于图片优化,kind 为 'IMAGE',数据将包含 buffer、etag、extension 和 revalidate 等属性。
返回 Promise<void>。
revalidateTag()#
| 参数 | 类型 | 描述 |
|---|---|---|
tag | string 或 string[] | 要重新验证的缓存标签。 |
返回 Promise<void>。了解更多关于重新验证数据或 revalidateTag() 函数的信息。
resetRequestCache()#
此方法会在下一个请求之前重置单个请求的临时内存缓存。
返回 void。
小知识:
revalidatePath是构建在缓存标签之上的便捷层。调用revalidatePath会调用你的revalidateTag函数,然后你可以自行决定是否基于路径为缓存键添加标签。
图片优化缓存#
cacheHandler 也可用于缓存来自 next/image 的优化后图片。要启用此功能,请在 next.config.js 中将 images.customCacheHandler 设为 true:
module.exports = {
cacheHandler: require.resolve('./cache-handler.js'),
images: {
customCacheHandler: true,
},
}小知识:此选择性启用标志将在下一个主要版本中成为默认行为。现在设置它可以让你提前让缓存处理器做好准备,以支持图片优化条目。
你可以使用 kind 属性来区分缓存条目类型,并在需要时单独处理图片,例如实现淘汰策略或将图片存储在不同位置。
处理图片缓存条目时,kind 为 'IMAGE',数据包含 buffer、etag、extension 和 revalidate 属性。
平台支持#
| 部署选项 | 是否支持 |
|---|---|
| Node.js 服务器 | 是 |
| Docker 容器 | 是 |
| 静态导出 | 否 |
| 适配器 | 视平台而定 |
了解在自托管 Next.js 时如何配置 ISR。
版本历史#
| 版本 | 变更内容 |
|---|---|
v16.2.0 | cacheHandler 支持图片优化缓存。 |
v14.1.0 | 重命名为 cacheHandler 并稳定。 |
v13.4.0 | incrementalCacheHandlerPath 支持 revalidateTag。 |
v13.4.0 | incrementalCacheHandlerPath 支持 standalone 输出。 |
v12.2.0 | 新增实验性 incrementalCacheHandlerPath。 |