NNext.js 中文网 GitHub

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

更改存储类型

您可能希望采用不同于默认内存方式的缓存存储方式。可以实现自定义处理程序,将缓存存储到磁盘、数据库或外部缓存服务中。原因包括:重启后保持持久性、降低内存占用,或与现有基础设施集成。

用法#

要配置自定义缓存处理程序:

  1. 在单独的文件中定义缓存处理程序,实现细节请参阅示例。
  2. 在 Next 配置文件中引用该文件路径
next.config.ts
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 nextConfig
next.config.js
module.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 导出:

ts
import type { CacheHandler, CacheEntry } from 'next/cache'

条目具有以下结构:

ts
interface CacheEntry {
  value: ReadableStream<Uint8Array>
  tags: string[]
  stale: number
  timestamp: number
  expire: number
  revalidate: number
}
属性类型描述
valueReadableStream<Uint8Array>以一次性流形式提供的缓存数据。
tagsstring[]缓存标签(不包括软标签)。
stalenumber客户端陈旧状态的持续时间(秒)。
timestampnumber条目的创建时间(毫秒时间戳)。
expirenumber条目允许使用的时长(秒)。
revalidatenumber条目应重新验证前的时长(秒)。

条目的值流#

每个处理程序通过 set() 写入条目,并通过 get() 提供条目。这两个方法都处理条目的序列化值,该值以 ReadableStream<Uint8Array> 的形式到达。该流有两个属性会约束每个实现:

  • 它只能被读取一次。 在 set() 中消费它,并在每次 get() 时基于存储的数据构建一个新流。已经被读取过的流无法为第二个读取者提供数据:它不会传送任何数据,或者在第一个读取者仍持有锁时抛出错误。
  • 它属于产生该条目的请求。 一旦 set() 解析,就不要再保留它。该流持有对该请求的引用,因此保留它会让该请求的内存一直被占用,直到您的条目被淘汰。pendingEntry promise 也是如此。Next.js 会为渲染保留自己的值副本,因此您的处理程序可以自由消费收到的流。

如何持久化数据由您决定。缓冲流并在数据块到达时将其通过管道传输到存储中都是可行的,只要您只消费一次即可。较大的条目值得采用管道方式:一个页面可能序列化为大量字节,而类似 S3 的后端可以接收它们,无需您的处理程序保留第二份副本。

还需要考虑以下两种情况:

  • 分流(Fan-out)。 如果单个条目需要到达两个目标位置(例如本地存储和远程存储),请使用 .tee() 并在 set() 解析前消费两个分支。分流并不是保留值的方法。保存下来的分支确实能为下一次读取提供服务,但它会持有源流、其缓冲的数据块以及产生它们的请求,而这些都不会计入您的存储所统计的大小。
  • 值中断。 流可能在渲染中途出错,导致您持有一个不完整的值。请决定是保留还是丢弃它。丢弃更安全,因为不完整的值会产生不完整的页面。这与部分写入的存储条目不同,后者由错误处理涵盖。

API 参考#

缓存处理程序必须实现 CacheHandler 接口,该接口包含以下五个方法。

set()#

为给定的缓存键存储缓存条目。

ts
set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>
参数类型描述
cacheKeystring用于存储条目的唯一键。
pendingEntryPromise<CacheEntry>解析为缓存条目的 promise。

返回 Promise<void>。

调用 set() 时条目可能仍在生成中,因此请先 await pendingEntry。然后消费值流并持久化它传送的数据,如条目的值流所述。

下面的示例采用缓冲方式,这是更简单的选择,也适合内存存储。远程处理程序可以将 entry.value 通过管道传输到上传中。

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

检索给定缓存键的缓存条目。

ts
get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>
参数类型描述
cacheKeystring缓存条目的唯一键。
softTagsstring[]从路由路径派生的隐式标签。使用方法请参阅软标签。

如果已存储条目,则返回 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() 中收到的流。

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

每个请求调用一次,在该处理程序类型的第一次缓存读取之前调用,以便处理程序可以从外部服务同步标签状态。

ts
refreshTags(): Promise<void>

返回 Promise<void>。

对于内存缓存,这可以是空操作。对于分布式缓存,可使用它从外部服务或数据库读取标签状态,使此实例在从自己的存储提供任何内容之前,就能了解到其他实例所做的失效操作。一个从此处理程序不读取任何内容的请求永远不会调用它。

js
const cacheHandler = {
  async refreshTags() {
    // 对于内存缓存,无需任何操作
    // 对于分布式缓存,从外部服务同步标签状态
  },
}

getExpiration()#

获取一组标签的最大重新验证时间戳。

ts
getExpiration(tags: string[]): Promise<number>
参数类型描述
tagsstring[]要检查过期时间的标签数组。

返回值:

  • 如果没有任何标签曾被重新验证,则为 0
  • 表示最近一次重新验证的时间戳(毫秒)
  • Infinity,表示软标签应改为在 get 方法中检查

如果您不跟踪标签的重新验证时间戳,则返回 0。否则,找出所有提供的标签中最近的重新验证时间戳。如果您希望改为在 get 方法中处理软标签检查,则返回 Infinity。

js
const cacheHandler = {
  async getExpiration(tags) {
    // 如果不跟踪标签重新验证,则返回 0
    return 0

    // 或者返回最近的重新验证时间戳
    // return Math.max(...tags.map(tag => tagTimestamps.get(tag) || 0));
  },
}

updateTags()#

当标签被重新验证或过期时调用。

ts
updateTags(tags: string[], durations?: { expire?: number }): Promise<void>
参数类型描述
tagsstring[]要更新的标签数组。
durations{ expire?: number }在基于配置(profile)的重新验证中出现;携带该配置的 expire 秒数。

您的处理程序应更新其内部状态,将这些标签标记为已失效。

durations 是否存在会告诉您是哪种失效类型:

  • 不存在:立即失效。携带这些标签的条目不应再被提供。updateTag() 和单参数的 revalidateTag() 走此路径,调用方期望其自己的下一次读取未命中。
  • 存在:这些标签现在变为陈旧状态,但携带它们的条目在后台刷新期间仍可被提供,直到 durations.expire 秒过去。revalidateTag(tag, 'max') 走此路径。

返回 Promise<void>。

您的处理程序应记录每个标签的失效时间。get() 会将这些时间与条目的 timestamp 进行比较,getExpiration() 对软标签做同样的事。软标签不存储在条目的 tags 中,因此删除携带某个标签的条目并不能涵盖 revalidatePath()。

js
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() 不会影响其他实例。

要在多个实例之间协调标签:

  1. updateTags() 在调用 revalidateTag() 时被调用。您的处理程序应将失效时间戳写入共享存储。
  2. refreshTags() 在每个请求中运行一次,在处理程序第一次读取之前。您的处理程序应从共享存储读取最近的失效事件,并更新其本地标签状态。
  3. getExpiration() 返回所有提供的标签中最近的重新验证时间戳。默认实现返回 Math.max(...timestamps, 0)。

以下是使用 Redis 进行分布式标签协调的示例:

cache-handlers/distributed-tags.js
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 和错误处理。

cache-handlers/memory-handler.js
// 条目保存的是序列化后的字节,而不是它们传入时的流
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() 中从存储的字节重建一个流:

cache-handlers/redis-handler.js
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.0cacheHandlers 已稳定,并从 experimental.cacheHandlers 移至顶层的 cacheHandlers 选项。
Next.js 中文网