Cloudflare
历史版本
Release 0.6
Caching

缓存机制

@opennextjs/cloudflare 支持 Next.js 缓存功能 (opens in a new tab)。

如何启用缓存

@opennextjs/cloudflare 通过项目的 OpenNext 配置支持多种缓存机制。

增量静态再生 (ISR)

增量缓存提供两种存储选项：

💡

Workers KV 采用最终一致性模型，默认 60 秒 TTL 下，全局更新可能需要最多 60 秒才能生效。

1. 创建 KV 命名空间
npx wrangler@latest kv namespace create <YOUR_NAMESPACE_NAME>
2. 添加 KV 命名空间和服务绑定到 Worker

应用中 Worker 使用的绑定名称为 NEXT_INC_CACHE_KV。 WORKER_SELF_REFERENCE 服务绑定应指向 Worker 自身，其中 <WORKER_NAME> 是 wrangler 配置文件中的名称。

// wrangler.jsonc
{
  // ...
  "name": "<WORKER_NAME>",
  "kv_namespaces": [
    {
      "binding": "NEXT_INC_CACHE_KV",
      "id": "<BINDING_ID>",
    },
  ],
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "<WORKER_NAME>",
    },
  ],
}
3. 配置缓存

在项目的 OpenNext 配置中启用 KV 缓存。

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
// ...
 
export default defineCloudflareConfig({
  incrementalCache: kvIncrementalCache,
  // ...
});
4. 配置队列

在项目的 OpenNext 配置中，启用缓存并设置队列。

Durable Object 队列会在需要时向页面发送重新验证请求，并支持请求去重。默认情况下，最多会有 10 个 Durable Object 队列实例，每个实例可以并行处理最多 5 个请求，总共支持 50 个并发 ISR 重新验证。

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
// ...
import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue";
 
export default defineCloudflareConfig({
  // ...
  queue: doQueue,
});

你还需要在 wrangler.jsonc 文件中添加一些绑定配置。

"durable_objects": {
    "bindings": [
      {
        "name": "NEXT_CACHE_DO_QUEUE",
        "class_name": "DurableObjectQueueHandler"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["DurableObjectQueueHandler"]
    }
  ],

你可以通过环境变量自定义队列的行为：

  • 单个 Durable Object 实例可以同时处理的重新验证最大数量 (NEXT_CACHE_DO_QUEUE_MAX_REVALIDATION)
  • 重新验证在被视为失败前允许的最大时间（毫秒）(NEXT_CACHE_DO_QUEUE_REVALIDATION_TIMEOUT_MS)
  • 重新验证失败后重试的间隔时间。如果再次失败，将以指数退避方式重试，直到达到最大重试间隔 (NEXT_CACHE_DO_QUEUE_RETRY_INTERVAL_MS)
  • 对路径进行重新验证的最大尝试次数 (NEXT_CACHE_DO_QUEUE_MAX_NUM_REVALIDATIONS)
  • 禁用此 Durable Object 的 SQLite。仅当你的增量缓存不是最终一致时才应使用 (NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE)
💡

队列还有两种额外模式可供使用：direct 和内存队列

  • 内存队列会对请求进行去重，但仅限于单个 isolate 范围内。它不完全适合生产环境部署，使用时需自行承担风险！

  • direct 队列模式用于调试目的，不建议在生产环境中使用。它仅在预览模式下工作（即 wrangler dev）

    对于使用 Page Router 的应用，res.revalidate 需要提供一个名为 WORKER_SELF_REFERENCE 的自引用服务绑定。

按需重新验证

标签重新验证机制可以使用 Cloudflare D1 (opens in a new tab) 数据库或带有 SqliteStorage 的 Durable Objects (opens in a new tab) 作为存储后端，用于记录标签、路径和重新验证时间的信息。

要使用按需重新验证功能，您还需要遵循 ISR 设置步骤。

💡

如果您的应用仅使用 pages 路由，则不需要标签缓存，可以跳过此步骤。 如果您的应用不使用 revalidateTag 和 revalidatePath，也可以跳过此步骤。

标签缓存有三种不同的选项可供选择：d1NextTagCache、doShardedTagCache 和 d1TagCache。 选择哪种方案应基于两个关键因素：

  1. 预期负载：考虑您预期的流量或数据量。
  2. 使用 revalidateTag / revalidatePath 的情况：评估这些功能的使用频率。

如果其中任一因素较为显著，建议选择分片数据库。此外，添加区域缓存可以进一步提升性能。

1. 创建 D1 数据库和服务绑定

在应用 worker 中使用的绑定名称为 NEXT_TAG_CACHE_D1。WORKER_SELF_REFERENCE 服务绑定应是对您 worker 的自我引用，其中 <WORKER_NAME> 是 wrangler 配置文件中的名称。

// wrangler.jsonc
{
  // ...
  "d1_databases": [
    {
      "binding": "NEXT_TAG_CACHE_D1",
      "database_id": "<DATABASE_ID>",
      "database_name": "<DATABASE_NAME>",
    },
  ],
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "<WORKER_NAME>",
    },
  ],
}
2. 创建标签重新验证表

D1 标签缓存需要一个 revalidations 表来跟踪按需重新验证的时间。

3. 配置缓存

在项目的 OpenNext 配置中，启用 KV 缓存并设置队列（如上所述）。队列会在需要时向页面发送重新验证请求，但不会对请求进行去重处理。

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
import d1NextTagCache from "@opennextjs/cloudflare/d1-next-tag-cache";
import memoryQueue from "@opennextjs/cloudflare/memory-queue";
 
export default defineCloudflareConfig({
  incrementalCache: kvIncrementalCache,
  tagCache: d1NextTagCache,
  queue: memoryQueue,
});