NNext.js 中文网 GitHub

自定义 Next.js 缓存处理器

配置用于存储和重新验证数据的 Next.js 缓存,使其使用 Redis、Memcached 或其他任何外部服务。

如果你想将缓存的页面和数据持久化到持久存储,或在 Next.js 应用程序的多个容器或实例之间共享缓存,可以配置 Next.js 缓存位置。

小知识:cacheHandler(单数)配置由 Next.js 专门用于服务端缓存操作,例如存储和重新验证 ISR、Route Handler 响应以及优化后的图片。它不用于 'use cache' 指令。对于 'use cache' 指令,请改用 cacheHandlers(复数)。cacheMaxMemorySize 与两者都不同,它分别设置各自的内存缓存大小。

next.config.js
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // 禁用默认的内存缓存
}

请参阅 Redis cacheHandler 示例了解可运行的实现,并参阅配置缓存了解由共享存储支持的处理器需要满足哪些条件。

API 参考#

缓存处理器可以实现以下方法:get、set、revalidateTag 和 resetRequestCache。

get()#

参数类型描述
keystring缓存值的键。
ctxobject包含缓存条目种类的上下文。

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()#

参数类型描述
keystring用于存储数据的键。
dataData 或 null要缓存的数据。
ctx{ tags: [] }提供的缓存标签。

data 对象包含一个 kind 属性,指示缓存条目的类型。对于图片优化,kind 为 'IMAGE',数据将包含 buffer、etag、extension 和 revalidate 等属性。

返回 Promise<void>。

revalidateTag()#

参数类型描述
tagstring 或 string[]要重新验证的缓存标签。

返回 Promise<void>。了解更多关于重新验证数据或 revalidateTag() 函数的信息。

resetRequestCache()#

此方法会在下一个请求之前重置单个请求的临时内存缓存。

返回 void。

小知识:

  • revalidatePath 是构建在缓存标签之上的便捷层。调用 revalidatePath 会调用你的 revalidateTag 函数,然后你可以自行决定是否基于路径为缓存键添加标签。

图片优化缓存#

cacheHandler 也可用于缓存来自 next/image 的优化后图片。要启用此功能,请在 next.config.js 中将 images.customCacheHandler 设为 true:

next.config.js
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.0cacheHandler 支持图片优化缓存。
v14.1.0重命名为 cacheHandler 并稳定。
v13.4.0incrementalCacheHandlerPath 支持 revalidateTag。
v13.4.0incrementalCacheHandlerPath 支持 standalone 输出。
v12.2.0新增实验性 incrementalCacheHandlerPath。
Next.js 中文网