Caching - OpenNext 中文文档

缓存

@opennextjs/cloudflare 支持缓存 (opens in a new tab)。

Next.js 在构建时预热缓存。构建时的值由 Workers Assets (opens in a new tab) 提供。

💡

Workers KV 是最终一致的，这意味着在使用默认的 60 秒 TTL 时，更新最多可能需要 60 秒才能在全球范围内反映出来。

如何启用缓存

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

增量静态再生 (ISR)

Cloudflare 的 ISR 适配器使用 Workers KV (opens in a new tab) 作为 Next.js 应用的缓存。Workers KV 速度快 (opens in a new tab) 并使用 Cloudflare 的分层缓存 (opens in a new tab) 来提高缓存命中率。当您向 Workers KV 写入缓存数据时，您写入的是任何 Cloudflare 位置都可以读取的存储。这意味着您的应用可以获取数据，将其缓存到 KV 中，然后随后来自世界各地的请求都可以从此缓存中读取。定价信息可在 Cloudflare 文档 (opens in a new tab) 中找到。

1. 创建 KV 命名空间

npx wrangler@latest kv namespace create <YOUR_NAMESPACE_NAME>

2. 将 KV 命名空间和服务绑定添加到您的 Worker

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

// wrangler.jsonc
{
  // ...
  "kv_namespaces": [
    {
      "binding": "NEXT_CACHE_WORKERS_KV",
      "id": "<BINDING_ID>",
    },
  ],
  "services": [
    {
      "binding": "NEXT_CACHE_REVALIDATION_WORKER",
      "service": "<WORKER_NAME>",
    },
  ],
}

3. 配置缓存

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

内存队列将在需要时向页面发送重新验证请求，并提供基于每个 isolate 的请求去重支持。在高流量或跨区域情况下可能仍会有重复请求。

⚠️

@opennextjs/cloudflare 提供的内存队列不完全适合生产部署，您可以自行承担风险使用它！

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

💡

队列的 direct 模式旨在用于调试目的，不建议在生产中使用。我们正在积极开发适合生产的解决方案。

按需重新验证

标签重新验证机制使用 Cloudflare D1 (opens in a new tab) 数据库作为其标签、路径和重新验证时间信息的后端存储。

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

💡

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

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

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

// wrangler.jsonc
{
  // ...
  "d1_databases": [
    {
      "binding": "NEXT_CACHE_D1",
      "database_id": "<DATABASE_ID>",
      "database_name": "<DATABASE_NAME>",
    },
  ],
  "services": [
    {
      "binding": "NEXT_CACHE_REVALIDATION_WORKER",
      "service": "<WORKER_NAME>",
    },
  ],
}

2. 创建标签重新验证表

D1 标签缓存需要两个表；一个记录标签/路径映射，另一个跟踪重新验证时间。

对于标签映射，默认表名是 tags，可以通过将 NEXT_CACHE_D1_TAGS_TABLE 环境变量设置为字符串来配置。

对于重新验证时间，默认表名是 revalidations，可以通过将 NEXT_CACHE_D1_REVALIDATIONS_TABLE 环境变量设置为字符串来配置。

Wrangler 可用于使用其 execute (opens in a new tab) 选项创建表。确保为您的本地开发数据库和远程数据库都创建表。

wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS tags (tag TEXT NOT NULL, path TEXT NOT NULL, UNIQUE(tag, path) ON CONFLICT REPLACE)"
wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS revalidations (tag TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, UNIQUE(tag) ON CONFLICT REPLACE)"

3. 配置缓存

在项目的 OpenNext 配置中，启用 KV 缓存并设置队列。队列将在需要时向页面发送重新验证请求，但不会去重请求。

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

4. 在部署期间初始化缓存

为了使缓存能够正确地使用构建时重新验证数据进行初始化，您需要设置一个命令作为部署步骤的一部分运行。

OpenNext 将在构建期间生成一个 SQL 文件，可用于设置您的 D1 数据库。

wrangler d1 execute NEXT_CACHE_D1 --file .open-next/cloudflare/cache-assets-manifest.sql

这应作为每次部署的一部分运行，以确保缓存填充了每个构建的初始重新验证数据。