cacheHandlers
为 Next.js 中的 use cache 指令配置自定义缓存处理程序。
cacheHandlers 配置允许您为 'use cache' 和 'use cache: remote' 定义自定义的缓存存储实现。这使您能够将缓存的组件和函数存储到外部服务中,或自定义缓存行为。'use cache: private' 不可配置。
何时使用自定义缓存处理程序#
大多数应用不需要自定义缓存处理程序。 默认的内存缓存在典型使用场景下表现良好。
自定义缓存处理程序适用于高级场景:您需要在多个实例之间共享缓存,或更改缓存的存储位置。例如,您可以为外部存储(如键值存储)配置自定义的 remote 处理程序,然后在代码中使用 'use cache' 进行内存缓存,使用 'use cache: remote' 进行外部存储,从而在同一应用中采用不同的缓存策略。
跨实例共享缓存
默认的内存缓存与每个 Next.js 进程相互隔离。如果您运行多个服务器或容器,每个实例都会拥有自己的缓存,既不与其他实例共享,也会在重启后丢失。
自定义处理程序可让您集成所有 Next.js 实例都能访问的共享存储系统(如 Redis、Memcached 或 DynamoDB)。
更改存储类型
您可能希望采用不同于默认内存方式的缓存存储方式。可以实现自定义处理程序,将缓存存储到磁盘、数据库或外部缓存服务中。原因包括:重启后保持持久性、降低内存占用,或与现有基础设施集成。
用法#
要配置自定义缓存处理程序:
- 在单独的文件中定义缓存处理程序,实现细节请参阅示例。
- 在 Next 配置文件中引用该文件路径
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheHandlers: {
default: require.resolve('./cache-handlers/default-handler.js'),
remote: require.resolve('./cache-handlers/remote-handler.js'),
},
}
export default nextConfigmodule.exports = {
cacheHandlers: {
default: require.resolve('./cache-handlers/default-handler.js'),
remote: require.resolve('./cache-handlers/remote-handler.js'),
},
}处理程序类型#
default:由'use cache'指令使用remote:由'use cache: remote'指令使用
如果不配置 cacheHandlers,Next.js 会对 default 和 remote 都使用内存中的 LRU(最近最少使用)缓存。您可以查看默认实现作为参考。
您还可以定义额外的命名处理程序(例如 sessions、analytics),并通过 'use cache: <name>' 引用它们。
请注意,'use cache: private' 不使用缓存处理程序,无法自定义。
CacheEntry 类型#
缓存处理程序存储并返回 CacheEntry 对象。该类型和 CacheHandler 均从 next/cache 导出:
import type { CacheHandler, CacheEntry } from 'next/cache'条目具有以下结构:
interface CacheEntry {
value: ReadableStream<Uint8Array>
tags: string[]
stale: number
timestamp: number
expire: number
revalidate: number
}| 属性 | 类型 | 描述 |
|---|---|---|
value | ReadableStream<Uint8Array> | 以一次性流形式提供的缓存数据。 |
tags | string[] | 缓存标签(不包括软标签)。 |
stale | number | 客户端陈旧状态的持续时间(秒)。 |
timestamp | number | 条目的创建时间(毫秒时间戳)。 |
expire | number | 条目允许使用的时长(秒)。 |
revalidate | number | 条目应重新验证前的时长(秒)。 |
条目的值流#
每个处理程序通过 set() 写入条目,并通过 get() 提供条目。这两个方法都处理条目的序列化值,该值以 ReadableStream<Uint8Array> 的形式到达。该流有两个属性会约束每个实现:
- 它只能被读取一次。 在
set()中消费它,并在每次get()时基于存储的数据构建一个新流。已经被读取过的流无法为第二个读取者提供数据:它不会传送任何数据,或者在第一个读取者仍持有锁时抛出错误。 - 它属于产生该条目的请求。 一旦
set()解析,就不要再保留它。该流持有对该请求的引用,因此保留它会让该请求的内存一直被占用,直到您的条目被淘汰。pendingEntrypromise 也是如此。Next.js 会为渲染保留自己的值副本,因此您的处理程序可以自由消费收到的流。
如何持久化数据由您决定。缓冲流并在数据块到达时将其通过管道传输到存储中都是可行的,只要您只消费一次即可。较大的条目值得采用管道方式:一个页面可能序列化为大量字节,而类似 S3 的后端可以接收它们,无需您的处理程序保留第二份副本。
还需要考虑以下两种情况:
- 分流(Fan-out)。 如果单个条目需要到达两个目标位置(例如本地存储和远程存储),请使用
.tee()并在set()解析前消费两个分支。分流并不是保留值的方法。保存下来的分支确实能为下一次读取提供服务,但它会持有源流、其缓冲的数据块以及产生它们的请求,而这些都不会计入您的存储所统计的大小。 - 值中断。 流可能在渲染中途出错,导致您持有一个不完整的值。请决定是保留还是丢弃它。丢弃更安全,因为不完整的值会产生不完整的页面。这与部分写入的存储条目不同,后者由错误处理涵盖。
API 参考#
缓存处理程序必须实现 CacheHandler 接口,该接口包含以下五个方法。
set()#
为给定的缓存键存储缓存条目。
set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>| 参数 | 类型 | 描述 |
|---|---|---|
cacheKey | string | 用于存储条目的唯一键。 |
pendingEntry | Promise<CacheEntry> | 解析为缓存条目的 promise。 |
返回 Promise<void>。
调用 set() 时条目可能仍在生成中,因此请先 await pendingEntry。然后消费值流并持久化它传送的数据,如条目的值流所述。
下面的示例采用缓冲方式,这是更简单的选择,也适合内存存储。远程处理程序可以将 entry.value 通过管道传输到上传中。
const cacheHandler = {
async set(cacheKey, pendingEntry) {
// 等待条目就绪
const entry = await pendingEntry
// 消费流,然后保留数据而不是流本身
const value = new Uint8Array(await new Response(entry.value).arrayBuffer())
// 存储到您的缓存系统中
cache.set(cacheKey, { ...entry, value })
},
}get()#
检索给定缓存键的缓存条目。
get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>| 参数 | 类型 | 描述 |
|---|---|---|
cacheKey | string | 缓存条目的唯一键。 |
softTags | string[] | 从路由路径派生的隐式标签。使用方法请参阅软标签。 |
如果已存储条目,则返回 CacheEntry 对象;否则返回 undefined。
您的 get 方法应从存储中检索缓存条目,当没有存储内容时返回 undefined。
您无需检查条目存在多久了。Next.js 在每次读取时都会将 timestamp 与条目自身的 expire 进行比较,并把过旧的条目视为未命中。当结果即将写入另一个服务端缓存时,它会对 revalidate 应用相同的检查,并且在开发服务器上会将条目保留得稍久一些,以使重新加载保持快速。您自己的时间检查只是重复了第一项工作。
这两个时间值对您的意义在于 Next.js 如何处理您返回的条目:
- 超过
expire后,条目会被丢弃并重新生成值。 - 超过
revalidate但仍在expire内时,条目会被提供,同时在后台生成新条目。
提前丢弃条目是一种策略选择,而非硬性要求。内置处理程序在 revalidate 时丢弃,因为如果内存中的条目可能在被读取之前就被淘汰,那么预热替代条目就是浪费工作。共享存储没有这个问题,可以一直提供到 expire。
不过,淘汰由您负责。Next.js 从不从您的存储中删除内容,因此请使用一种能回收无人再读取的条目的机制:基于 expire 派生的 TTL,或类似内置处理程序中那样有大小限制的 LRU。在提供条目时检查其存在时间并不算淘汰,因为它只会触及那些仍在被读取的键。
失效与这两个时间值无关。当某个标签告诉您条目已过期时,您有两种选择:
- 返回
undefined。该条目视为缺失,Next.js 立即重新生成它。 - 返回带有
revalidate: -1的条目。Next.js 会提供该条目并在后台重新生成,因为负的revalidate总是表示过去。
每次命中时都要将存储的数据包装到新流中,绝不要使用在 set() 中收到的流。
const cacheHandler = {
async get(cacheKey, softTags) {
const entry = cache.get(cacheKey)
if (!entry) return undefined
// 无需检查时间:Next.js 自己会将 `timestamp` 与 `expire` 进行比较。
// `entry.value` 保存的是存储的字节,因此将它们包装到一个新流中
return {
...entry,
value: new ReadableStream({
start(controller) {
controller.enqueue(entry.value)
controller.close()
},
}),
}
},
}refreshTags()#
每个请求调用一次,在该处理程序类型的第一次缓存读取之前调用,以便处理程序可以从外部服务同步标签状态。
refreshTags(): Promise<void>返回 Promise<void>。
对于内存缓存,这可以是空操作。对于分布式缓存,可使用它从外部服务或数据库读取标签状态,使此实例在从自己的存储提供任何内容之前,就能了解到其他实例所做的失效操作。一个从此处理程序不读取任何内容的请求永远不会调用它。
const cacheHandler = {
async refreshTags() {
// 对于内存缓存,无需任何操作
// 对于分布式缓存,从外部服务同步标签状态
},
}getExpiration()#
获取一组标签的最大重新验证时间戳。
getExpiration(tags: string[]): Promise<number>| 参数 | 类型 | 描述 |
|---|---|---|
tags | string[] | 要检查过期时间的标签数组。 |
返回值:
- 如果没有任何标签曾被重新验证,则为
0 - 表示最近一次重新验证的时间戳(毫秒)
Infinity,表示软标签应改为在get方法中检查
如果您不跟踪标签的重新验证时间戳,则返回 0。否则,找出所有提供的标签中最近的重新验证时间戳。如果您希望改为在 get 方法中处理软标签检查,则返回 Infinity。
const cacheHandler = {
async getExpiration(tags) {
// 如果不跟踪标签重新验证,则返回 0
return 0
// 或者返回最近的重新验证时间戳
// return Math.max(...tags.map(tag => tagTimestamps.get(tag) || 0));
},
}updateTags()#
当标签被重新验证或过期时调用。
updateTags(tags: string[], durations?: { expire?: number }): Promise<void>| 参数 | 类型 | 描述 |
|---|---|---|
tags | string[] | 要更新的标签数组。 |
durations | { expire?: number } | 在基于配置(profile)的重新验证中出现;携带该配置的 expire 秒数。 |
您的处理程序应更新其内部状态,将这些标签标记为已失效。
durations 是否存在会告诉您是哪种失效类型:
- 不存在:立即失效。携带这些标签的条目不应再被提供。
updateTag()和单参数的revalidateTag()走此路径,调用方期望其自己的下一次读取未命中。 - 存在:这些标签现在变为陈旧状态,但携带它们的条目在后台刷新期间仍可被提供,直到
durations.expire秒过去。revalidateTag(tag, 'max')走此路径。
返回 Promise<void>。
您的处理程序应记录每个标签的失效时间。get() 会将这些时间与条目的 timestamp 进行比较,getExpiration() 对软标签做同样的事。软标签不存储在条目的 tags 中,因此删除携带某个标签的条目并不能涵盖 revalidatePath()。
const cacheHandler = {
async updateTags(tags, durations) {
const now = Date.now()
for (const tag of tags) {
const timestamps = tagTimestamps.get(tag) ?? {}
if (durations) {
// 在刷新期间继续提供,并在 `durations.expire` 秒后过期
timestamps.stale = now
if (durations.expire !== undefined) {
timestamps.expired = now + durations.expire * 1000
}
} else {
// 立即过期
timestamps.expired = now
}
tagTimestamps.set(tag, timestamps)
}
},
}软标签#
软标签是 Next.js 根据路由路径自动生成的隐式标签。路径中的每个路由段都会获得一个布局标签,此外还有叶路由本身。例如,路由 /blog/hello 会为 /layout、/blog/layout、/blog/hello/layout 和 /blog/hello 生成软标签。这些标签在内部以 _N_T_ 作为前缀。
软标签使 revalidatePath() 能够通过同一套基于标签的缓存系统工作。当调用 revalidatePath('/blog/hello') 时,它会使与该路径的软标签相关联的所有缓存条目失效。
在缓存处理程序 API 中,软标签作为 softTags 参数传递给 get() 方法。您的处理程序应检查是否有任何软标签在缓存条目的 timestamp 之后失效(通过 getExpiration() 或直接进行时间戳比较)。
如果失效时间晚于条目,请使用 get() 中描述的任一选项将该条目报告为已过期。内置处理程序两者都用:对于已过期的标签返回 undefined,对于陈旧标签返回 revalidate: -1。
分布式标签协调#
运行多个 Next.js 实例时,标签失效必须在实例之间协调。默认的内存处理程序只在本地跟踪标签,因此在一个实例上调用 revalidateTag() 不会影响其他实例。
要在多个实例之间协调标签:
updateTags()在调用revalidateTag()时被调用。您的处理程序应将失效时间戳写入共享存储。refreshTags()在每个请求中运行一次,在处理程序第一次读取之前。您的处理程序应从共享存储读取最近的失效事件,并更新其本地标签状态。getExpiration()返回所有提供的标签中最近的重新验证时间戳。默认实现返回Math.max(...timestamps, 0)。
以下是使用 Redis 进行分布式标签协调的示例:
const { createClient } = require('redis')
const client = createClient({ url: process.env.REDIS_URL })
client.connect()
// 标签时间戳的本地缓存,通过 refreshTags 同步
const localTagTimestamps = new Map()
module.exports = {
// ... get() 和 set() 方法 ...
async refreshTags() {
// 从 Redis 同步标签失效时间戳
// 使用专门的集合来跟踪标签键,避免扫描整个键空间
const tagKeys = await client.sMembers('revalidated-tags')
if (tagKeys.length > 0) {
const values = await client.mGet(tagKeys.map((k) => `tag:${k}`))
for (let i = 0; i < tagKeys.length; i++) {
localTagTimestamps.set(tagKeys[i], Number(values[i]))
}
}
},
async getExpiration(tags) {
const timestamps = tags.map((tag) => localTagTimestamps.get(tag) || 0)
return Math.max(...timestamps, 0)
},
async updateTags(tags, durations) {
const now = Date.now()
const pipeline = client.multi()
for (const tag of tags) {
pipeline.set(`tag:${tag}`, String(now))
pipeline.sAdd('revalidated-tags', tag)
localTagTimestamps.set(tag, now)
}
await pipeline.exec()
},
}有关标签架构的完整说明(包括软标签和多实例注意事项),请参阅重新验证的工作原理。
错误处理#
缓存操作应采用防御式实现:
set()失败:响应仍会提供给用户,因为set()是在响应流已经开始流动后异步调用的。缓存条目会丢失,下一次请求会触发一次全新的渲染。即便如此,也要捕获自己的错误:被拒绝的set()会加入该请求挂起的重新验证工作,在那里它会表现为一个失败的后台任务,而不是渲染错误。get()失败:您的处理程序应捕获内部错误并返回undefined(即"缓存未命中"信号)。框架不会用 try/catch 包裹get(),因此get()中未处理的异常会作为渲染错误向上传播。- 部分写入:如果缓存条目被部分写入后再被读取,行为是未定义的。请使用原子写入或"先写后重命名"的模式,避免提供部分条目。
示例#
下面的示例展示处理程序如何满足 API 契约。它们省略了生产环境处理程序必须添加的淘汰、错误处理和多实例协调。cache-handler-redis 示例是对两个缓存 API 更完整的 Redis 实现,其 README 列出了涵盖更多场景的社区处理程序。
用于学习和调试的内存处理程序#
此处理程序将条目保存在 Map 中,因此可用于记录或检查 Next.js 存储了什么以及标签如何使其失效。它按进程运行,没有淘汰机制。内置处理程序同样基于内存,并增加了有大小限制的 LRU 和错误处理。
// 条目保存的是序列化后的字节,而不是它们传入时的流
const cache = new Map()
const pendingSets = new Map()
// 标签失效时间(毫秒):{ stale, expired }
const tagTimestamps = new Map()
function streamFromBytes(bytes) {
return new ReadableStream({
start(controller) {
controller.enqueue(bytes)
controller.close()
},
})
}
module.exports = {
async get(cacheKey, softTags) {
// 等待任何挂起的 set 操作完成
const pendingPromise = pendingSets.get(cacheKey)
if (pendingPromise) {
await pendingPromise
}
const entry = cache.get(cacheKey)
if (!entry) {
return undefined
}
// 无需检查时间:Next.js 自己会将 `timestamp` 与 `expire` 进行比较。
// 软标签由 Next.js 通过 `getExpiration()` 检查。
// 这个 `Map` 也没有淘汰机制,而真正的处理程序需要它。
let revalidate = entry.revalidate
for (const tag of entry.tags) {
const { stale = 0, expired = 0 } = tagTimestamps.get(tag) ?? {}
if (expired > entry.timestamp && expired <= Date.now()) {
return undefined
}
if (stale > entry.timestamp) {
revalidate = -1
}
}
// 每次命中都会获得一个基于存储字节的专属流
return { ...entry, revalidate, value: streamFromBytes(entry.value) }
},
async set(cacheKey, pendingEntry) {
// 创建一个 promise 来跟踪此 set 操作
let resolvePending
const pendingPromise = new Promise((resolve) => {
resolvePending = resolve
})
pendingSets.set(cacheKey, pendingPromise)
try {
// 等待条目就绪
const entry = await pendingEntry
// 内存存储会缓冲流。存储流本身,或者它的一个分支,
// 都会让产生该条目的请求保持存活。
const value = new Uint8Array(
await new Response(entry.value).arrayBuffer()
)
cache.set(cacheKey, { ...entry, value })
} finally {
resolvePending()
pendingSets.delete(cacheKey)
}
},
async refreshTags() {
// 标签状态位于此进程中,因此无需同步
},
async getExpiration(tags) {
return Math.max(
...tags.map((tag) => tagTimestamps.get(tag)?.expired ?? 0),
0
)
},
async updateTags(tags, durations) {
const now = Date.now()
for (const tag of tags) {
const timestamps = tagTimestamps.get(tag) ?? {}
if (durations) {
// 在刷新期间继续提供,并在 `durations.expire` 秒后过期
timestamps.stale = now
if (durations.expire !== undefined) {
timestamps.expired = now + durations.expire * 1000
}
} else {
// 立即过期
timestamps.expired = now
}
tagTimestamps.set(tag, timestamps)
}
},
}外部存储模式#
由 Redis 或数据库支持的处理程序必须对每个条目进行序列化。在 set() 中排空流,并在 get() 中从存储的字节重建一个流:
const { createClient } = require('redis')
const client = createClient({ url: process.env.REDIS_URL })
client.connect()
module.exports = {
async get(cacheKey, softTags) {
// 从 Redis 检索
const stored = await client.get(cacheKey)
if (!stored) return undefined
// 反序列化条目
const data = JSON.parse(stored)
// 从存储的数据重建 ReadableStream
return {
value: new ReadableStream({
start(controller) {
controller.enqueue(Buffer.from(data.value, 'base64'))
controller.close()
},
}),
tags: data.tags,
stale: data.stale,
timestamp: data.timestamp,
expire: data.expire,
revalidate: data.revalidate,
}
},
async set(cacheKey, pendingEntry) {
const entry = await pendingEntry
// 读取流以获取数据
const reader = entry.value.getReader()
const chunks = []
try {
while (true) {
const { done, value } = await reader.read()
if (done) break
chunks.push(value)
}
} finally {
reader.releaseLock()
}
// 合并数据块并序列化以供 Redis 存储
const data = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)))
await client.set(
cacheKey,
JSON.stringify({
value: data.toString('base64'),
tags: entry.tags,
stale: entry.stale,
timestamp: entry.timestamp,
expire: entry.expire,
revalidate: entry.revalidate,
}),
// `EX` 需要一个正整数。
// 按照定义,`expire: Infinity`("永不过期")
// 意味着完全没有 TTL,因此省略 `EX`,让 Redis 永久保留该键。
Number.isFinite(entry.expire)
? { EX: Math.max(1, Math.ceil(entry.expire)) }
: {}
)
},
// refreshTags()、getExpiration() 和 updateTags() 也需要共享状态。
// 处理程序的这一半请参阅"分布式标签协调"。
}平台支持#
| 部署选项 | 支持情况 |
|---|---|
| Node.js 服务器 | 是 |
| Docker 容器 | 是 |
| 静态导出 | 否 |
| 适配器 | 视平台而定 |
版本历史#
| 版本 | 变更 |
|---|---|
v16.0.0 | cacheHandlers 已稳定,并从 experimental.cacheHandlers 移至顶层的 cacheHandlers 选项。 |