mcpField
C
cloudflare-nextjs

cloudflare-nextjs

github.com/secondsky云与 DevOps240252 次安装5 周前更新
代码仓库

关于 cloudflare-nextjs

介绍如何使用 OpenNext adapter 将 Next.js 应用部署到 Cloudflare Workers 的 Skill，重点涵盖 Workers 专属配置、绑定、缓存、部署流程与故障排查，而非通用 Next.js 模式。

主要功能

  1. 01OpenNext Workers 配置指引
  2. 02迁移现有项目
  3. 03本地预览与部署脚本
  4. 04Cloudflare 绑定与类型生成
  5. 05缓存配置说明
  6. 06Workers 错误排查

适用场景

  1. 01将 Next.js 应用部署到 Workers
  2. 02迁移现有 Next.js 项目
  3. 03配置绑定与缓存
  4. 04诊断构建或运行时错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/secondsky/claude-skills --skill cloudflare-nextjs

安装后在 Claude Code 中输入/cloudflare-nextjs确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
workflow-diagram.md
references/
advanced.md
bindings-and-services.md
caching.md
database-client-example.ts
dev-deploy-and-env.md
error-catalog-extended.md
feature-support.md
known-issues.md
open-next.config.ts
package.json
troubleshooting.md
wrangler.jsonc
scripts/
analyze-bundle.sh
setup-existing-project.sh
setup-new-project.sh

详细介绍

OpenNext Cloudflare 适配器 — Workers 上的 Next.js

使用 OpenNext 适配器（@opennextjs/cloudflare）将 Next.js 应用部署到 Cloudflare Workers。适配器会执行 package.json 构建脚本，构建标准的 Next.js 应用，然后将输出转换为可在 Workers 运行时上运行的格式，并使用 Node.js 兼容层（nodejs_compat）——而不是 Edge 运行时。

关键要求（配置错误会导致构建或运行时失败）

要求值原因
运行时Node.js（默认）。移除所有 export const runtime = "edge";不支持 Edge 运行时；OpenNext 使用 nodejs_compat。
compatibility_flags["nodejs_compat", "global_fetch_strictly_public"]提供 Node API，并允许在应用代码中使用 fetch()。
compatibility_date≥ 2024-09-23；建议使用 ≥ 2025-05-05（FinalizationRegistry）较早的日期会导致 FinalizationRegistry、DO 和其他功能出错。
Wrangler部署需要 ≥ 3.99.0；使用 keep_names 需要 ≥ 4.13.0；使用稳定的远程绑定需要 ≥ 4.36.0文档中的功能门槛。
Next.js支持 v16 的所有次要版本和补丁版本；支持 v14 和 v15 的最新次要版本；v14 将于 2026 年第一季度弃用概述页面中的说明。
Worker 大小（gzip）Free 为 3 MiB / Paid 为 10 MiB（仅指压缩后）Cloudflare 的硬性限制。

**Windows：**无法保证完全可用（Next.js 工具链存在问题）。请使用 WSL、Linux 虚拟机或 Linux/macOS CI。请参阅已知问题 #1305。

区分：此技能与 nextjs

  • nextjs 技能 → 框架、App Router、Server Components、Cache Components 模式，适用于任何平台（Vercel、可自托管等）。适用于 async params、proxy.ts 迁移、"use cache"。
  • 本技能（cloudflare-nextjs） → 通过 OpenNext 适配器将 Next.js 部署到 Workers：wrangler.jsonc、open-next.config.ts、getCloudflareContext、缓存层级、绑定、版本偏移保护、多 Worker 以及 Workers 特有的错误。

**proxy.ts 注意事项（Next 16）：**Next 16 将 middleware.ts 重命名为 proxy.ts，但 @opennextjs/cloudflare 尚不识别 proxy.ts（问题 #1277）——在 Cloudflare 上，请继续使用 middleware.ts。这是唯一不适用此处 nextjs 技能指南的地方。

快速开始

新建项目（推荐）
npm create cloudflare@latest -- my-next-app --framework=next --platform=workers

C3 会搭建 Next.js 应用、安装 @opennextjs/cloudflare、创建 wrangler.jsonc + open-next.config.ts + .dev.vars、配置 package.json 脚本，并且（如果启用了 R2）创建用于缓存的 R2 存储桶。

现有 Next.js 项目（一个命令）
npx @opennextjs/cloudflare migrate

migrate 会自动完成以下操作：安装适配器和 wrangler、创建 wrangler.jsonc/open-next.config.ts/.dev.vars、更新脚本、添加 public/_headers、将 .open-next 添加到 .gitignore、将 initOpenNextCloudflareForDev() 配置到 next.config.ts 中，以及创建并配置 R2 缓存存储桶（仅当账户启用了 R2 时）。

手动安装（如果你不想运行 migrate） 
npm install @opennextjs/cloudflare@latest
npm install --save-dev wrangler@latest

然后创建这三个文件（请参阅 references/wrangler.jsonc、references/open-next.config.ts、references/package.json），并添加 dev/preview/deploy/upload/cf-typegen 脚本。升级前请锁定适配器版本并进行审核——请参阅 dependency-upgrade 技能。

四个脚本
// package.json
{
  "dev":     "next dev",                                                       // fast HMR via Next dev server
  "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",   // build + run in workerd locally
  "deploy":  "opennextjs-cloudflare build && opennextjs-cloudflare deploy",    // build + serve immediately
  "upload":  "opennextjs-cloudflare build && opennextjs-cloudflare upload",    // build + upload a version (gradual rollout)
  "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
}
  • dev — 提供最快的反馈循环；将 initOpenNextCloudflareForDev() 添加到 next.config.ts，以便 getCloudflareContext() 在本地通过模拟/远程绑定正常工作。
  • preview — 在实际的 Workers 运行时（而不是 Node）中运行。部署前务必运行，以发现仅在运行时出现的问题。
  • deploy — 填充远程缓存，然后运行 wrangler deploy。应用会立即提供服务。
  • upload — 填充远程缓存，然后运行 wrangler versions upload。不会自动提供服务；适用于渐进式部署。

build、preview、deploy、upload 都会隐式调用 populateCache——无需手动运行。

开发环境中的 next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = { /* ... */ };
export default nextConfig;

import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
initOpenNextCloudflareForDev();

访问 Cloudflare 绑定 — getCloudflareContext()

不要使用 process.env 访问绑定。 官方 API 是 @opennextjs/cloudflare 中的 getCloudflareContext()。

import { getCloudflareContext } from "@opennextjs/cloudflare";

export async function GET() {
  const { env, cf, ctx } = getCloudflareContext();
  await env.MY_KV.put("foo", "bar");
  return new Response(await env.MY_KV.get("foo"));
}

静态路由（ISR/SSG）必须使用异步模式——并请注意：静态生成期间会使用密钥/本地值。

const { env } = await getCloudflareContext({ async: true });

TypeScript 类型：npm run cf-typegen 会生成 cloudflare-env.d.ts（每次更改绑定后都要重新运行）。

远程绑定（本地开发 → 实际资源）：在 Wrangler 4.36.0 中已稳定。在较旧版本的 wrangler 上，通过 initOpenNextCloudflareForDev({ experimental: { remoteBindings: true } }) 启用，并在绑定选项中使用 experimental_remote（而非 remote）键。注意：远程绑定也会在构建期间使用。

完整模式（D1/R2/KV/AI/Hyperdrive、Drizzle、Prisma、Stripe）→ references/bindings-and-services.md。

缓存 — 三个组件，三个层级

OpenNext 的缓存由三部分组成：增量缓存（存储）、队列（去重/重新验证）、标签缓存（按需调用 revalidateTag/revalidatePath）。

站点类型增量缓存队列标签缓存适用情况
仅 SSG（无重新验证）staticAssetsIncrementalCache + enableCacheInterception: true无无速度最快；只读
小型站点（ISR/按需）r2IncrementalCachedoQueued1NextTagCache低流量；D1 标签缓存
大型/高流量站点withRegionalCache(r2IncrementalCache, { mode: "long-lived" })doQueuedoShardedTagCache({ baseShardSize: 12 }) + purgeCache({ type: "direct" })按 DO 分片；按需使用时添加缓存清除

保留的绑定名称（请勿重复使用）：ASSETS、WORKER_SELF_REFERENCE、NEXT_INC_CACHE_R2_BUCKET、NEXT_CACHE_DO_QUEUE、NEXT_TAG_CACHE_D1、NEXT_TAG_CACHE_DO_SHARDED、NEXT_CACHE_DO_PURGE、IMAGES。

  • 避免将 Workers KV 用于增量缓存——它最终一致，可能会无限期保留过期数据。
  • 缓存拦截 + PPR：目前不兼容；默认不启用缓存拦截，且无法与 PPR 配合使用。
  • 按需重新验证需要同时配置标签缓存和缓存清除组件（缓存清除仅适用于 zone/自定义域名；需要 CACHE_PURGE_API_TOKEN + CACHE_PURGE_ZONE_ID 密钥）。
  • Pages Router 的 res.revalidate 需要一个名为 WORKER_SELF_REFERENCE 的自引用服务绑定。
  • 请求头注意事项：Worker 不会在静态资源前运行，因此 next.config.ts 中针对 public/ 和不可变构建文件的 headers() 不会生效。请使用 public/_headers。

深入了解（所有选项、环境变量、区域模式、从 0.6 迁移）→ references/caching.md 和 references/known-issues.md。

常见集成（精简版——完整模式见参考文档）

  • Drizzle + D1/Hyperdrive/PG、Prisma + D1/PG/Hyperdrive — 通过 react 的 cache() 使用请求作用域客户端；PG 连接池设置 maxUses: 1；使用 getCloudflareContext({ async: true }) 支持 ISR/SSG；Prisma 需要 previewFeatures = ["driverAdapters"]，schema.prisma 中不设置输出目录，并设置 serverExternalPackages: ["@prisma/client", ".prisma/client"]。→ references/bindings-and-services.md
  • Stripe — Workers 没有 node:https；传入 httpClient: Stripe.createFetchHttpClient()。→ references/bindings-and-services.md
  • 图像优化 — 在 wrangler.jsonc 中设置 images.binding: "IMAGES"，或为区域使用自定义加载器（/cdn-cgi/image/...）。不支持 minimumCacheTTL 和 dangerouslyAllowLocalIP；自定义加载器会绕过中间件，并忽略 remotePatterns。→ references/advanced.md
  • 环境变量 — 使用 Next.js .env 文件（不要只用 .dev.vars）；在 .dev.vars 中通过 NEXTJS_ENV 选择环境；部署时使用 --keep-vars；密钥只能写入，不能读取。→ references/dev-deploy-and-env.md
  • 自定义 worker（添加 scheduled、Durable Object 导出）— 将 main 指向重新导出生成的 fetch 处理程序的 worker。→ references/advanced.md
  • 多 worker（将中间件与服务器拆分）— 减少每个 worker 的内存用量和冷启动；与预览 URL、版本偏移保护以及 @opennextjs/cloudflare deploy 不兼容。→ references/advanced.md
  • 版本偏移保护（基于预览 URL 的版本匹配）— cloudflare.skewProtection.enabled、run_worker_first: true、getDeploymentId()、环境变量 CF_WORKER_NAME/CF_PREVIEW_DOMAIN/CF_WORKERS_SCRIPTS_API_TOKEN/CF_ACCOUNT_ID。带有 Durable Object 的 Workers 会禁用此功能（将 DO 移至单独的 worker）。→ references/advanced.md

常见错误（完整列表 → references/error-catalog-extended.md）

1. 超出 Worker 大小限制

"Your Worker exceeded the size limit of 3 MiB"（Free）/"10 MiB"（Paid）。仅计算 gzip 后的大小。Free → 升级到 Paid。Paid → 分析捆绑包：运行 npx @opennextjs/cloudflare build，然后检查 .open-next/server-functions/default/handler.mjs.meta.json（使用 ESBuild Bundle Analyzer 可视化）；移除未使用的依赖，使用动态导入。

2. 无法代表其他请求执行 I/O

跨请求复用全局数据库客户端（例如 postgres、pg Pool）。在请求处理程序内部创建客户端（或使用 react 的 cache()），并将 PG 连接池的 maxUses 设为 1。

3. NPM 包导入 / "Could not resolve <package>"

启用 nodejs_compat，确保 compatibility_date ≥ 2024-09-23。某些包提供 workerd 导出——将它们添加到 next.config.ts 中的 serverExternalPackages（例如 @prisma/client、.prisma/client、postgres、jose、react-textarea-autosize、@libsql/isomorphic-ws）。或者在 .env 中设置：WRANGLER_BUILD_CONDITIONS="" + WRANGLER_BUILD_PLATFORM="node"。

4. SSRF（CVE-2025-6087）——版本 < 1.3.0

/_next/image SSRF。立即升级：@opennextjs/cloudflare@^1.3.0（当前版本：^1.18.1）。

5. 无法加载代码块 server/chunks/ssr/<name>.js

适配器版本过旧，无法处理 Turbopack 构建。将 @opennextjs/cloudflare 升级到最新版，或切换到 webpack（运行 next build，不带 --turbo）。

6. ReferenceError: FinalizationRegistry is not defined

compatibility_date 太旧。在 wrangler.jsonc 中将其设置为 "compatibility_date": "2025-05-05"（或更晚）。

7. Uncaught ReferenceError: __name is not defined

Wrangler 的 esbuild keep-names 会将 __name 注入生成的脚本字符串，一些库（例如 next-themes）会在运行时对其执行 eval。在 wrangler.jsonc 中设置 "keep_names": false（需要 Wrangler ≥ 4.13.0）。调试时将无法看到原始函数名称。

8. populateCache remote 期间出现“Failed to send request to R2 worker”／403

受 Cloudflare Access 保护的账户会拦截 open-next-cache-populate 辅助 Worker。不要为它创建单独的 Access 应用；请在覆盖 *.<account>.workers.dev 的现有应用中添加 Service Auth 策略（Include = Any Access Service Token），创建服务令牌，并导出 CLOUDFLARE_ACCESS_CLIENT_ID / CLOUDFLARE_ACCESS_CLIENT_SECRET。

已知未修复问题（实时跟踪）

请务必查看问题跟踪器——撰写本文时，这些问题仍会反复出现：

#问题解决方法
#1171v1.18.0 会导致 R2 缓存填充失败（已固定版本）固定使用 1.17.x，或升级到修复版本之后
#1277不支持 proxy.js——Next 16 将 proxy.ts 重命名后会导致路由失效在 Cloudflare 上保留 middleware.ts
#1130 / #1225cacheComponents: true 会崩溃（Unexpected identifier '$' / Connection closed）禁用 cacheComponents
#1321React 水合偶发不匹配（约 9% 的加载会出现）—
#1322 / #1214Hyperdrive + pg / @prisma/adapter-pg 打包失败—
#1315基于时间的 fetch 缓存重新验证在 Next 16 上会静默失效（已部署）—
#1305Windows + Turbopack 路由返回 500使用 Linux/macOS 或 webpack
#1317@cf-wasm/photon 的 Turbopack 构建失败（原始 .wasm）使用 webpack
#1326Webpack 分块内联会漏掉具名分块 → Unknown chunk N—
#617不支持 Node 中间件（Next 15.2+）（功能请求）使用标准中间件

完整问题跟踪器：https://github.com/opennextjs/opennextjs-cloudflare/issues

功能支持

功能状态备注
App Router、Pages Router、Route Handlers、动态路由✅完全支持
React Server Components、Server Actions✅完全支持
SSG、SSR、ISR✅完全支持
中间件✅除外：Node 中间件（Next 15.2+，问题 #617）
图像优化✅通过 Cloudflare Images（绑定或自定义加载器）
部分预渲染（PPR）✅但目前缓存拦截与 PPR 不兼容
可组合缓存（'use cache'）、after✅
Turbopack✅但请参阅 #1305、#1317、#1326——webpack 更稳妥
Edge Runtime❌仅支持 Node runtime；移除 runtime = "edge"
Node 中间件（15.2+）❌#617

相关技能

技能用途
nextjs在任何平台上使用 Next.js 框架／App Router 模式（proxy.ts／缓存／Server Components 参考）
cloudflare-workers通用 Workers 模式；框架选择树（Hono 与 OpenNext）
drizzle-orm-d1深入了解 Drizzle + D1（注意：OpenNext 不得打包 Wrangler——请参阅其错误目录）
cloudflare-r2 / cloudflare-kv / cloudflare-d1深入了解特定服务
dependency-upgrade固定版本／审查 @opennextjs/cloudflare（生产流量）

何时加载参考资料

文件加载时机
references/caching.md选择或配置增量缓存／队列缓存／标签缓存、区域缓存、清除缓存时
references/bindings-and-services.md集成 D1/R2/KV/AI/Hyperdrive、配置 Drizzle/Prisma 请求级客户端、集成 Stripe 时
references/dev-deploy-and-env.md设置开发／预览／部署、配置 Workers Builds CI、环境变量／密钥时
references/advanced.md配置自定义 Worker、多 Worker、偏斜保护、静态资源、keep_names、workerd 软件包、图像优化时
references/known-issues.md处理 DO 构建警告、从 0.6 迁移到 1.0.0-beta 时
references/error-catalog-extended.md遇到上述前 8 种以外的任何错误时
references/troubleshooting.md进行分步调试，以及性能分析／最小化处理时
references/feature-support.md查看详细的功能兼容性矩阵时
references/wrangler.jsonc查看小型站点和大型站点的 wrangler 模板（包含所有保留绑定）时
references/open-next.config.ts查看可运行配置中的三个缓存层级时
references/database-client-example.ts查看请求级数据库客户端模式时
references/package.json查看参考脚本和版本时

来源

版本：@opennextjs/cloudflare ^1.18.1 · Next.js 14/15/16 · Wrangler ≥ 3.99.0 · compatibility_date ≥ 2025-05-05 上次验证时间：2026-08-05

评论

支持 Markdown