Cloudflare Next.js部署指南：使用OpenNext适配器将Next.js应用部署到Workers

cloudflare-nextjs by jackspace/claudeskillz

73 周安装量

10 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jackspace/claudeskillz --skill cloudflare-nextjs

开发云服务部署策略

🇨🇳中文介绍

Cloudflare Next.js 部署技能

使用 OpenNext Cloudflare 适配器将 Next.js 应用程序部署到 Cloudflare Workers，实现生产就绪的无服务器 Next.js 托管。

使用场景

将 Next.js 应用程序（App Router 或 Pages Router）部署到 Cloudflare Workers
需要在 Cloudflare 上实现服务器端渲染（SSR）、静态站点生成（SSG）或增量静态再生（ISR）
将现有的 Next.js 应用从 Vercel、AWS 或其他平台迁移到 Cloudflare
使用 Cloudflare 服务（D1、R2、KV、Workers AI）构建全栈 Next.js 应用程序
需要在 Workers 上使用 React 服务器组件、服务器操作或 Next.js 中间件
希望通过 Cloudflare 网络实现全球边缘部署

核心概念

OpenNext 适配器架构

OpenNext Cloudflare 适配器（@opennextjs/cloudflare）将 Next.js 构建输出转换为 Cloudflare Worker 兼容的格式。这与标准的 Next.js 部署有根本区别：

需要 Node.js 运行时：在 Workers 中使用 Node.js 运行时（非 Edge 运行时）
双重开发工作流：在 Next.js 开发服务器和 workerd 运行时中同时测试
自定义构建流水线：next build → OpenNext 转换 → Worker 部署
Cloudflare 特定配置：需要 wrangler.jsonc 和 open-next.config.ts

与标准 Next.js 的关键区别

方面	标准 Next.js

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

包导出的环境变量

如果使用具有多个导出条件的 npm 包，请创建 .env：

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

这确保 Wrangler 在有 node 导出时优先使用它。

Cloudflare 绑定集成

在 wrangler.jsonc 中添加绑定：

{
  "name": "your-app-name",
  "compatibility_date": "2025-05-05",
  "compatibility_flags": ["nodejs_compat"],

  // D1 数据库
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production-db",
      "database_id": "your-database-id"
    }
  ],

  // R2 存储
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "your-bucket"
    }
  ],

  // KV 存储
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "your-kv-id"
    }
  ],

  // Workers AI
  "ai": {
    "binding": "AI"
  }
}

通过 process.env 在 Next.js 中访问绑定：

// app/api/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  // 访问 Cloudflare 绑定
  const env = process.env as any;

  // D1 数据库查询
  const result = await env.DB.prepare('SELECT * FROM users').all();

  // R2 存储访问
  const file = await env.BUCKET.get('file.txt');

  // KV 存储访问
  const value = await env.KV.get('key');

  // Workers AI 推理
  const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
    prompt: 'Hello AI'
  });

  return Response.json({ result });
}

错误预防（10+ 个已记录的错误）

1. Worker 大小限制超出（3 MiB - 免费计划）

错误："Your Worker exceeded the size limit of 3 MiB"

原因：Workers 免费计划将 Worker 大小限制为 3 MiB（gzip 压缩后）

升级到 Workers 付费计划（10 MiB 限制）
分析包大小并移除未使用的依赖项
使用动态导入来代码分割大型依赖项

npx opennextjs-cloudflare build
cd .open-next/server-functions/default
# 使用 ESBuild Bundle Analyzer 分析 handler.mjs.meta.json

2. Worker 大小限制超出（10 MiB - 付费计划）

错误："Your Worker exceeded the size limit of 10 MiB"

原因：不必要的代码被打包到 Worker 中

调试工作流：

运行 npx opennextjs-cloudflare build
导航到 .open-next/server-functions/default
使用 ESBuild Bundle Analyzer 分析 handler.mjs.meta.json
识别并移除/外部化大型依赖项

3. FinalizationRegistry 未定义

错误："ReferenceError: FinalizationRegistry is not defined"

原因：wrangler.jsonc 中的 compatibility_date 太旧

解决方案：将 compatibility_date 更新为 2025-05-05 或更高版本：

{
  "compatibility_date": "2025-05-05"  // FinalizationRegistry 所需的最低版本
}

4. 无法代表不同请求执行 I/O

错误："Cannot perform I/O on behalf of a different request"

原因：数据库客户端在全局创建并在多个请求间重用

// ❌ 错误：全局 DB 客户端
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function GET() {
  // 这将失败 - pool 在不同的请求上下文中创建
  const result = await pool.query('SELECT * FROM users');
  return Response.json(result);
}

解决方案：在请求处理程序内部创建数据库客户端：

// ✅ 正确：请求作用域的 DB 客户端
import { Pool } from 'pg';

export async function GET() {
  // 在请求上下文中创建客户端
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const result = await pool.query('SELECT * FROM users');
  await pool.end();
  return Response.json(result);
}

替代方案：使用 Cloudflare D1（专为 Workers 设计）而非外部数据库：

// ✅ 最佳：使用 D1（无需连接池）
export async function GET(request: NextRequest) {
  const env = process.env as any;
  const result = await env.DB.prepare('SELECT * FROM users').all();
  return Response.json(result);
}

5. NPM 包导入失败

错误："Could not resolve '<package>'"

原因：缺少 nodejs_compat 标志或包导出条件

解决方案 1：启用 nodejs_compat 标志：

{
  "compatibility_flags": ["nodejs_compat"]
}

解决方案 2：对于具有多个导出的包，创建 .env：

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

6. 加载块失败（Turbopack）

错误："Failed to load chunk server/chunks/ssr/"

原因：Next.js 使用 Turbopack 构建（next build --turbo）

解决方案：使用标准构建（适配器不支持 Turbopack）：

{
  "scripts": {
    "build": "next build"  // ✅ 正确
    // "build": "next build --turbo"  // ❌ 不要使用 Turbopack
  }
}

7. SSRF 漏洞（CVE-2025-6087）

漏洞：通过 /_next/image 端点进行服务器端请求伪造

受影响版本：@opennextjs/cloudflare < 1.3.0

解决方案：升级到 1.3.0 或更高版本：

npm install --save-dev @opennextjs/cloudflare@^1.3.0

影响：允许未经身份验证的用户代理任意远程内容

8. Durable Objects 绑定警告

警告："You have defined bindings to the following internal Durable Objects... will not work in local development, but they should work in production"

原因：OpenNext 使用 Durable Objects 进行缓存（DOQueueHandler、DOShardedTagCache）

解决方案：可以安全忽略 - 警告是预期行为

替代方案（用于抑制警告）：在具有自身配置的单独 Worker 中定义 Durable Objects

9. Prisma + D1 中间件冲突

错误：在 Next.js 中间件中使用 @prisma/client + @prisma/adapter-d1 时出现构建错误

原因：在中间件上下文中初始化数据库

变通方案：在路由处理程序中初始化 Prisma 客户端，而非中间件

10. cross-fetch 库错误

错误：使用依赖 cross-fetch 的库时出现错误

原因：OpenNext 修补了部署包，导致 cross-fetch 在原生 fetch 可用时尝试使用 Node.js 库

解决方案：直接使用原生 fetch API 而非 cross-fetch：

// ✅ 使用原生 fetch
const response = await fetch('https://api.example.com/data');

// ❌ 避免使用 cross-fetch
// import fetch from 'cross-fetch';

11. Windows 开发问题

问题：不保证完整的 Windows 支持

原因：底层 Next.js 工具在 Windows 上的问题

使用 WSL（Windows Subsystem for Linux）
使用 Linux 虚拟机
使用基于 Linux 的 CI/CD 进行部署

功能	状态	备注
App Router	✅ 完全支持	最新的 App Router 功能可用
Pages Router	✅ 完全支持	支持旧版 Pages Router
路由处理器	✅ 完全支持	API 路由按预期工作
React 服务器组件	✅ 完全支持	RSC 功能完整
服务器操作	✅ 完全支持	服务器操作可用
SSG	✅ 完全支持	静态站点生成
SSR	✅ 完全支持	服务器端渲染
ISR	✅ 完全支持	增量静态再生
中间件	✅ 支持	除了 Node.js 中间件（15.2+）
图片优化	✅ 支持	通过 Cloudflare Images
部分预渲染（PPR）	✅ 支持	Next.js 中的实验性功能
可组合缓存	✅ 支持	`'use cache'` 指令
响应流式传输	✅ 支持	流式响应可用
`next/after` API	✅ 支持	响应后异步工作
Node.js 中间件（15.2+）	❌ 不支持	计划未来支持
Edge 运行时	❌ 不支持	使用 Node.js 运行时

与 Cloudflare 服务集成

D1 数据库（SQL）

// app/api/users/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as any;

  const result = await env.DB.prepare(
    'SELECT * FROM users WHERE active = ?'
  ).bind(true).all();

  return Response.json(result.results);
}

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const { name, email } = await request.json();

  const result = await env.DB.prepare(
    'INSERT INTO users (name, email) VALUES (?, ?)'
  ).bind(name, email).run();

  return Response.json({ id: result.meta.last_row_id });
}

Wrangler 配置：

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production-db",
      "database_id": "your-database-id"
    }
  ]
}

另请参阅：cloudflare-d1 技能以获取完整的 D1 模式

R2 存储（对象存储）

// app/api/upload/route.ts
import type { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const formData = await request.formData();
  const file = formData.get('file') as File;

  // 上传到 R2
  await env.BUCKET.put(file.name, file.stream(), {
    httpMetadata: {
      contentType: file.type
    }
  });

  return Response.json({ success: true, filename: file.name });
}

export async function GET(request: NextRequest) {
  const env = process.env as any;
  const { searchParams } = new URL(request.url);
  const filename = searchParams.get('file');

  const object = await env.BUCKET.get(filename);
  if (!object) {
    return new Response('Not found', { status: 404 });
  }

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream'
    }
  });
}

另请参阅：cloudflare-r2 技能以获取完整的 R2 模式

Workers AI（模型推理）

// app/api/ai/route.ts
import type { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const { prompt } = await request.json();

  const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
    prompt
  });

  return Response.json(response);
}

Wrangler 配置：

{
  "ai": {
    "binding": "AI"
  }
}

另请参阅：cloudflare-workers-ai 技能以获取完整的 AI 模式

KV 存储（键值）

// app/api/cache/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as any;
  const { searchParams } = new URL(request.url);
  const key = searchParams.get('key');

  const value = await env.KV.get(key);
  return Response.json({ key, value });
}

export async function PUT(request: NextRequest) {
  const env = process.env as any;
  const { key, value, ttl } = await request.json();

  await env.KV.put(key, value, { expirationTtl: ttl });
  return Response.json({ success: true });
}

另请参阅：cloudflare-kv 技能以获取完整的 KV 模式

Next.js 图片优化通过 Cloudflare Images 工作。在 open-next.config.ts 中配置：

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

export default defineCloudflareConfig({
  imageOptimization: {
    loader: 'cloudflare'
  }
});

在组件中使用：

import Image from 'next/image';

export default function Avatar() {
  return (
    <Image
      src="/avatar.jpg"
      alt="User avatar"
      width={200}
      height={200}
      // 通过 Cloudflare Images 自动优化
    />
  );
}

计费：Cloudflare Images 使用单独计费

在 open-next.config.ts 中配置缓存行为：

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

export default defineCloudflareConfig({
  // 自定义缓存配置
  cache: {
    // 覆盖默认缓存行为
    // 参见：https://opennext.js.org/cloudflare/caching
  }
});

默认行为：OpenNext 提供合理的缓存默认值

高级用法：参见 OpenNext 官方缓存文档

Node.js 中间件（Next.js 15.2+）
- 在 Next.js 15.2 中引入
- 计划在未来版本中支持
- 目前使用标准中间件
Edge 运行时
- 仅支持 Node.js 运行时
- 从你的应用中移除 export const runtime = "edge"
完整的 Windows 支持
- 不保证在 Windows 上的完整开发支持
- 使用 WSL、虚拟机或基于 Linux 的 CI/CD

免费计划：3 MiB 限制（gzip 压缩后）
付费计划：10 MiB 限制（gzip 压缩后）
在开发过程中监控包大小
使用动态导入进行代码分割

外部数据库客户端（PostgreSQL、MySQL）必须是请求作用域的
无法跨请求重用连接（Workers 限制）
对于数据库需求，优先使用 Cloudflare D1（专为 Workers 设计）

从本地机器部署

# 在一个命令中构建和部署
npm run deploy

# 或分步执行：
npx opennextjs-cloudflare build
npx opennextjs-cloudflare deploy

在你的 CI/CD 系统中配置部署命令：

GitHub Actions：.github/workflows/deploy.yml
GitLab CI：.gitlab-ci.yml
Cloudflare Workers Builds：自动检测 npm run deploy

环境变量：在 Cloudflare 仪表板或 CI/CD 系统中设置密钥

在 Cloudflare 仪表板中添加自定义域名：

导航到 Workers & Pages
选择你的 Worker
设置 → 域名和路由
添加自定义域名

DNS：域名必须在 Cloudflare 上（需要区域）

为 Cloudflare 绑定生成类型：

npm run cf-typegen

创建包含绑定类型的 cloudflare-env.d.ts：

// cloudflare-env.d.ts（自动生成）
interface CloudflareEnv {
  DB: D1Database;
  BUCKET: R2Bucket;
  KV: KVNamespace;
  AI: Ai;
}

在路由处理器中使用：

import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as CloudflareEnv;
  // 现在 env.DB、env.BUCKET 等已具有类型
}

本地测试（开发）

# Next.js 开发服务器（快速迭代）
npm run dev

本地测试（类生产环境）

# Workerd 运行时（捕获 Workers 特定问题）
npm run preview

部署前始终在 preview 模式下测试：

# 构建并在 workerd 中运行
npm run preview

# 测试绑定（D1、R2、KV、AI）
# 测试中间件
# 测试 API 路由
# 测试 SSR/ISR 行为

从其他平台迁移

复制现有的 Next.js 项目
运行上述现有项目迁移步骤
在 Cloudflare 仪表板中更新环境变量
替换 Vercel 特定功能：
- Vercel Postgres → Cloudflare D1
- Vercel Blob → Cloudflare R2
- Vercel KV → Cloudflare KV
- Vercel Edge Config → Cloudflare KV
使用 npm run preview 彻底测试
使用 npm run deploy 部署

从 AWS / 其他平台迁移

与 Vercel 迁移过程相同 - 适配器会自动处理 Next.js 标准功能。

cloudflare-worker-base - 使用 Hono + Vite + React 的基础 Worker 设置
cloudflare-d1 - D1 数据库集成
cloudflare-r2 - R2 对象存储
cloudflare-kv - KV 键值存储
cloudflare-workers-ai - Workers AI 集成
cloudflare-vectorize - 用于 RAG 的向量数据库

# 新项目
npm create cloudflare@latest -- my-next-app --framework=next

# 开发
npm run dev      # 快速迭代（Next.js 开发服务器）
npm run preview  # 在 workerd 中测试（类生产环境）

# 部署
npm run deploy   # 构建并部署到 Cloudflare

# TypeScript
npm run cf-typegen  # 生成绑定类型

// wrangler.jsonc
{
  "compatibility_date": "2025-05-05",  // 最低要求！
  "compatibility_flags": ["nodejs_compat"]  // 必需！
}

❌ 使用 Edge 运行时 → ✅ 使用 Node.js 运行时
❌ 全局 DB 客户端 → ✅ 请求作用域的客户端
❌ 旧的 compatibility_date → ✅ 使用 2025-05-05+
❌ 缺少 nodejs_compat → ✅ 添加到 compatibility_flags
❌ 仅在 dev 中测试 → ✅ 部署前始终测试 preview
❌ 使用 Turbopack → ✅ 使用标准 Next.js 构建

生产环境测试：官方 Cloudflare 支持和活跃社区 节省 Token：与手动设置相比约 59% 预防错误：10+ 个已记录问题 最后验证：2025-10-21

🇺🇸English

Cloudflare Next.js Deployment Skill

Deploy Next.js applications to Cloudflare Workers using the OpenNext Cloudflare adapter for production-ready serverless Next.js hosting.

Use This Skill When

Deploying Next.js applications (App Router or Pages Router) to Cloudflare Workers
Need server-side rendering (SSR), static site generation (SSG), or incremental static regeneration (ISR) on Cloudflare
Migrating existing Next.js apps from Vercel, AWS, or other platforms to Cloudflare
Building full-stack Next.js applications with Cloudflare services (D1, R2, KV, Workers AI)
Need React Server Components, Server Actions, or Next.js middleware on Workers
Want global edge deployment with Cloudflare's network

Key Concepts

OpenNext Adapter Architecture

The OpenNext Cloudflare adapter (@opennextjs/cloudflare) transforms Next.js build output into Cloudflare Worker-compatible format. This is fundamentally different from standard Next.js deployments:

Node.js Runtime Required : Uses Node.js runtime in Workers (NOT Edge runtime)
Dual Development Workflow : Test in both Next.js dev server AND workerd runtime
Custom Build Pipeline : next build → OpenNext transformation → Worker deployment
Cloudflare-Specific Configuration : Requires wrangler.jsonc and open-next.config.ts

Critical Differences from Standard Next.js

Aspect	Standard Next.js	Cloudflare Workers
Runtime	Node.js or Edge	Node.js (via nodejs_compat)
Dev Server	`next dev`	`next dev` + `opennextjs-cloudflare preview`
Deployment	Platform-specific	`opennextjs-cloudflare deploy`
Worker Size	No limit	3 MiB (free) / 10 MiB (paid)
Database Connections	Global clients OK	Must be request-scoped
Image Optimization

Setup Patterns

New Project Setup

Use Cloudflare's create-cloudflare (C3) CLI to scaffold a new Next.js project pre-configured for Workers:

npm create cloudflare@latest -- my-next-app --framework=next

What this does :

Runs Next.js official setup tool (create-next-app)
Installs @opennextjs/cloudflare adapter
Creates wrangler.jsonc with correct configuration
Creates open-next.config.ts for caching configuration
Adds deployment scripts to package.json
Optionally deploys immediately to Cloudflare

Development workflow :

npm run dev      # Next.js dev server (fast reloads)
npm run preview  # Test in workerd runtime (production-like)
npm run deploy   # Build and deploy to Cloudflare

Existing Project Migration

To add the OpenNext adapter to an existing Next.js application:

1. Install the adapter

npm install --save-dev @opennextjs/cloudflare

2. Create wrangler.jsonc

{
  "name": "my-next-app",
  "compatibility_date": "2025-05-05",
  "compatibility_flags": ["nodejs_compat"]
}

Critical configuration :

compatibility_date: Minimum2025-05-05 (for FinalizationRegistry support)
compatibility_flags: Must includenodejs_compat (for Node.js runtime)

3. Create open-next.config.ts

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

export default defineCloudflareConfig({
  // Caching configuration (optional)
  // See: https://opennext.js.org/cloudflare/caching
});

4. Update package.json scripts

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
    "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  }
}

Script purposes :

dev: Next.js development server (fast iteration)
preview: Build + run in workerd runtime (test before deploy)
deploy: Build + deploy to Cloudflare
cf-typegen: Generate TypeScript types for Cloudflare bindings

5. Ensure Node.js runtime (not Edge)

Remove Edge runtime exports from your app:

// ❌ REMOVE THIS (Edge runtime not supported)
export const runtime = "edge";

// ✅ Use Node.js runtime (default)
// No export needed - Node.js is default

Development Workflow

Dual Testing Strategy

Always test in BOTH environments :

Next.js Dev Server (npm run dev)
- Fast hot reloading
- Best developer experience
- Runs in Node.js (not production runtime)
- Use for rapid iteration
Workerd Runtime (npm run preview)
- Runs in production-like environment
- Catches runtime-specific issues
- Slower rebuild times
- Required before deployment

When to Use Each

# Iterating on UI/logic → Use Next.js dev server
npm run dev

# Testing integrations (D1, R2, KV) → Use preview
npm run preview

# Before deploying → ALWAYS test preview
npm run preview

# Deploy to production
npm run deploy

Configuration Requirements

Wrangler Configuration

Minimum requirements in wrangler.jsonc:

{
  "name": "your-app-name",
  "compatibility_date": "2025-05-05",  // Minimum for FinalizationRegistry
  "compatibility_flags": ["nodejs_compat"]  // Required for Node.js runtime
}

Environment Variables for Package Exports

If using npm packages with multiple export conditions, create .env:

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

This ensures Wrangler prioritizes the node export when available.

Cloudflare Bindings Integration

Add bindings in wrangler.jsonc:

{
  "name": "your-app-name",
  "compatibility_date": "2025-05-05",
  "compatibility_flags": ["nodejs_compat"],

  // D1 Database
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production-db",
      "database_id": "your-database-id"
    }
  ],

  // R2 Storage
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "your-bucket"
    }
  ],

  // KV Storage
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "your-kv-id"
    }
  ],

  // Workers AI
  "ai": {
    "binding": "AI"
  }
}

Access bindings in Next.js via process.env:

// app/api/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  // Access Cloudflare bindings
  const env = process.env as any;

  // D1 Database query
  const result = await env.DB.prepare('SELECT * FROM users').all();

  // R2 Storage access
  const file = await env.BUCKET.get('file.txt');

  // KV Storage access
  const value = await env.KV.get('key');

  // Workers AI inference
  const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
    prompt: 'Hello AI'
  });

  return Response.json({ result });
}

Error Prevention (10+ Documented Errors)

1. Worker Size Limit Exceeded (3 MiB - Free Plan)

Error : "Your Worker exceeded the size limit of 3 MiB"

Cause : Workers Free plan limits Worker size to 3 MiB (gzip-compressed)

Solutions :

Upgrade to Workers Paid plan (10 MiB limit)
Analyze bundle size and remove unused dependencies
Use dynamic imports to code-split large dependencies

Bundle analysis :

npx opennextjs-cloudflare build
cd .open-next/server-functions/default
# Analyze handler.mjs.meta.json with ESBuild Bundle Analyzer

Source : https://opennext.js.org/cloudflare/troubleshooting#worker-size-limits

2. Worker Size Limit Exceeded (10 MiB - Paid Plan)

Error : "Your Worker exceeded the size limit of 10 MiB"

Cause : Unnecessary code bundled into Worker

Debug workflow :

Run npx opennextjs-cloudflare build
Navigate to .open-next/server-functions/default
Analyze handler.mjs.meta.json using ESBuild Bundle Analyzer
Identify and remove/externalize large dependencies

Source : https://opennext.js.org/cloudflare/troubleshooting#worker-size-limits

3. FinalizationRegistry Not Defined

Error : "ReferenceError: FinalizationRegistry is not defined"

Cause : compatibility_date in wrangler.jsonc is too old

Solution : Update compatibility_date to 2025-05-05 or later:

{
  "compatibility_date": "2025-05-05"  // Minimum for FinalizationRegistry
}

Source : https://opennext.js.org/cloudflare/troubleshooting#finalizationregistry-is-not-defined

4. Cannot Perform I/O on Behalf of Different Request

Error : "Cannot perform I/O on behalf of a different request"

Cause : Database client created globally and reused across requests

Problem code :

// ❌ WRONG: Global DB client
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function GET() {
  // This will fail - pool created in different request context
  const result = await pool.query('SELECT * FROM users');
  return Response.json(result);
}

Solution : Create database clients inside request handlers:

// ✅ CORRECT: Request-scoped DB client
import { Pool } from 'pg';

export async function GET() {
  // Create client within request context
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const result = await pool.query('SELECT * FROM users');
  await pool.end();
  return Response.json(result);
}

Alternative : Use Cloudflare D1 (designed for Workers) instead of external databases:

// ✅ BEST: Use D1 (no connection pooling needed)
export async function GET(request: NextRequest) {
  const env = process.env as any;
  const result = await env.DB.prepare('SELECT * FROM users').all();
  return Response.json(result);
}

Source : https://opennext.js.org/cloudflare/troubleshooting#cannot-perform-io-on-behalf-of-a-different-request

5. NPM Package Import Failures

Error : "Could not resolve '<package>'"

Cause : Missing nodejs_compat flag or package export conditions

Solution 1 : Enable nodejs_compat flag:

{
  "compatibility_flags": ["nodejs_compat"]
}

Solution 2 : For packages with multiple exports, create .env:

WRANGLER_BUILD_CONDITIONS=""
WRANGLER_BUILD_PLATFORM="node"

Source : https://opennext.js.org/cloudflare/troubleshooting#npm-packages-fail-to-import

6. Failed to Load Chunk (Turbopack)

Error : "Failed to load chunk server/chunks/ssr/"

Cause : Next.js built with Turbopack (next build --turbo)

Solution : Use standard build (Turbopack not supported by adapter):

{
  "scripts": {
    "build": "next build"  // ✅ Correct
    // "build": "next build --turbo"  // ❌ Don't use Turbopack
  }
}

Source : https://opennext.js.org/cloudflare/troubleshooting#failed-to-load-chunk

7. SSRF Vulnerability (CVE-2025-6087)

Vulnerability : Server-Side Request Forgery via /_next/image endpoint

Affected versions : @opennextjs/cloudflare < 1.3.0

Solution : Upgrade to version 1.3.0 or later:

npm install --save-dev @opennextjs/cloudflare@^1.3.0

Impact : Allows unauthenticated users to proxy arbitrary remote content

Source : https://github.com/advisories/GHSA-rvpw-p7vw-wj3m

8. Durable Objects Binding Warnings

Warning : "You have defined bindings to the following internal Durable Objects... will not work in local development, but they should work in production"

Cause : OpenNext uses Durable Objects for caching (DOQueueHandler, DOShardedTagCache)

Solution : Safe to ignore - warning is expected behavior

Alternative (to suppress warning): Define Durable Objects in separate Worker with own config

Source : https://opennext.js.org/cloudflare/known-issues#caching-durable-objects

9. Prisma + D1 Middleware Conflicts

Error : Build errors when using @prisma/client + @prisma/adapter-d1 in Next.js middleware

Cause : Database initialization in middleware context

Workaround : Initialize Prisma client in route handlers, not middleware

Source : https://github.com/opennextjs/opennextjs-cloudflare/issues/471

10. cross-fetch Library Errors

Error : Errors when using libraries that depend on cross-fetch

Cause : OpenNext patches deployment package causing cross-fetch to try using Node.js libraries when native fetch is available

Solution : Use native fetch API directly instead of cross-fetch:

// ✅ Use native fetch
const response = await fetch('https://api.example.com/data');

// ❌ Avoid cross-fetch
// import fetch from 'cross-fetch';

Source : https://opennext.js.org/cloudflare/troubleshooting

11. Windows Development Issues

Issue : Full Windows support not guaranteed

Cause : Underlying Next.js tooling issues on Windows

Solutions :

Use WSL (Windows Subsystem for Linux)
Use virtual machine with Linux
Use Linux-based CI/CD for deployments

Source : https://opennext.js.org/cloudflare#windows-support

Feature Support Matrix

Feature	Status	Notes
App Router	✅ Fully Supported	Latest App Router features work
Pages Router	✅ Fully Supported	Legacy Pages Router supported
Route Handlers	✅ Fully Supported	API routes work as expected
React Server Components	✅ Fully Supported	RSC fully functional
Server Actions	✅ Fully Supported	Server Actions work
SSG	✅ Fully Supported	Static Site Generation
SSR	✅ Fully Supported	Server-Side Rendering
ISR

Source : https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/#next-js-supported-features

Integration with Cloudflare Services

D1 Database (SQL)

// app/api/users/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as any;

  const result = await env.DB.prepare(
    'SELECT * FROM users WHERE active = ?'
  ).bind(true).all();

  return Response.json(result.results);
}

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const { name, email } = await request.json();

  const result = await env.DB.prepare(
    'INSERT INTO users (name, email) VALUES (?, ?)'
  ).bind(name, email).run();

  return Response.json({ id: result.meta.last_row_id });
}

Wrangler config :

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "production-db",
      "database_id": "your-database-id"
    }
  ]
}

See also : cloudflare-d1 skill for complete D1 patterns

R2 Storage (Object Storage)

// app/api/upload/route.ts
import type { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const formData = await request.formData();
  const file = formData.get('file') as File;

  // Upload to R2
  await env.BUCKET.put(file.name, file.stream(), {
    httpMetadata: {
      contentType: file.type
    }
  });

  return Response.json({ success: true, filename: file.name });
}

export async function GET(request: NextRequest) {
  const env = process.env as any;
  const { searchParams } = new URL(request.url);
  const filename = searchParams.get('file');

  const object = await env.BUCKET.get(filename);
  if (!object) {
    return new Response('Not found', { status: 404 });
  }

  return new Response(object.body, {
    headers: {
      'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream'
    }
  });
}

See also : cloudflare-r2 skill for complete R2 patterns

Workers AI (Model Inference)

// app/api/ai/route.ts
import type { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const env = process.env as any;
  const { prompt } = await request.json();

  const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
    prompt
  });

  return Response.json(response);
}

Wrangler config :

{
  "ai": {
    "binding": "AI"
  }
}

See also : cloudflare-workers-ai skill for complete AI patterns

KV Storage (Key-Value)

// app/api/cache/route.ts
import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as any;
  const { searchParams } = new URL(request.url);
  const key = searchParams.get('key');

  const value = await env.KV.get(key);
  return Response.json({ key, value });
}

export async function PUT(request: NextRequest) {
  const env = process.env as any;
  const { key, value, ttl } = await request.json();

  await env.KV.put(key, value, { expirationTtl: ttl });
  return Response.json({ success: true });
}

See also : cloudflare-kv skill for complete KV patterns

Image Optimization

Next.js image optimization works via Cloudflare Images. Configure in open-next.config.ts:

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

export default defineCloudflareConfig({
  imageOptimization: {
    loader: 'cloudflare'
  }
});

Usage in components:

import Image from 'next/image';

export default function Avatar() {
  return (
    <Image
      src="/avatar.jpg"
      alt="User avatar"
      width={200}
      height={200}
      // Automatically optimized via Cloudflare Images
    />
  );
}

Billing : Cloudflare Images usage is billed separately

Docs : https://developers.cloudflare.com/images/

Caching Configuration

Configure caching behavior in open-next.config.ts:

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

export default defineCloudflareConfig({
  // Custom cache configuration
  cache: {
    // Override default cache behavior
    // See: https://opennext.js.org/cloudflare/caching
  }
});

Default behavior : OpenNext provides sensible caching defaults

Advanced usage : See official OpenNext caching documentation

Known Limitations

Not Yet Supported

Node.js Middleware (Next.js 15.2+)
- Introduced in Next.js 15.2
- Support planned for future releases
- Use standard middleware for now
Edge Runtime
- Only Node.js runtime supported
- Remove export const runtime = "edge" from your app
Full Windows Support
- Development on Windows not fully guaranteed
- Use WSL, VM, or Linux-based CI/CD

Worker Size Constraints

Free plan : 3 MiB limit (gzip-compressed)
Paid plan : 10 MiB limit (gzip-compressed)
Monitor bundle size during development
Use dynamic imports for code splitting

Database Connections

External database clients (PostgreSQL, MySQL) must be request-scoped
Cannot reuse connections across requests (Workers limitation)
Prefer Cloudflare D1 for database needs (designed for Workers)

Deployment

Deploy from Local Machine

# Build and deploy in one command
npm run deploy

# Or step by step:
npx opennextjs-cloudflare build
npx opennextjs-cloudflare deploy

Deploy from CI/CD

Configure deployment command in your CI/CD system:

npm run deploy

Examples :

GitHub Actions: .github/workflows/deploy.yml
GitLab CI: .gitlab-ci.yml
Cloudflare Workers Builds: Auto-detects npm run deploy

Environment variables : Set secrets in Cloudflare dashboard or CI/CD system

Custom Domains

Add custom domain in Cloudflare dashboard:

Navigate to Workers & Pages
Select your Worker
Settings → Domains & Routes
Add custom domain

DNS : Domain must be on Cloudflare (zone required)

TypeScript Support

Generate types for Cloudflare bindings:

npm run cf-typegen

Creates cloudflare-env.d.ts with types for your bindings:

// cloudflare-env.d.ts (auto-generated)
interface CloudflareEnv {
  DB: D1Database;
  BUCKET: R2Bucket;
  KV: KVNamespace;
  AI: Ai;
}

Use in route handlers:

import type { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const env = process.env as CloudflareEnv;
  // Now env.DB, env.BUCKET, etc. are typed
}

Testing

Local Testing (Development)

# Next.js dev server (fast iteration)
npm run dev

Local Testing (Production-like)

# Workerd runtime (catches Workers-specific issues)
npm run preview

Integration Testing

Always test in preview mode before deploying:

# Build and run in workerd
npm run preview

# Test bindings (D1, R2, KV, AI)
# Test middleware
# Test API routes
# Test SSR/ISR behavior

Migration from Other Platforms

From Vercel

Copy existing Next.js project
Run existing project migration steps (above)
Update environment variables in Cloudflare dashboard
Replace Vercel-specific features:
- Vercel Postgres → Cloudflare D1
- Vercel Blob → Cloudflare R2
- Vercel KV → Cloudflare KV
- Vercel Edge Config → Cloudflare KV
Test thoroughly with npm run preview
Deploy with npm run deploy

From AWS / Other Platforms

Same process as Vercel migration - the adapter handles Next.js standard features automatically.

Resources

Official Documentation

OpenNext Cloudflare : https://opennext.js.org/cloudflare
Cloudflare Next.js Guide : https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/
Next.js Docs : https://nextjs.org/docs

Troubleshooting

Troubleshooting Guide : https://opennext.js.org/cloudflare/troubleshooting
Known Issues : https://opennext.js.org/cloudflare/known-issues
GitHub Issues : https://github.com/opennextjs/opennextjs-cloudflare/issues

Related Skills

cloudflare-worker-base - Base Worker setup with Hono + Vite + React
cloudflare-d1 - D1 database integration
cloudflare-r2 - R2 object storage
cloudflare-kv - KV key-value storage
cloudflare-workers-ai - Workers AI integration
cloudflare-vectorize - Vector database for RAG

Quick Reference

Essential Commands

# New project
npm create cloudflare@latest -- my-next-app --framework=next

# Development
npm run dev      # Fast iteration (Next.js dev server)
npm run preview  # Test in workerd (production-like)

# Deployment
npm run deploy   # Build and deploy to Cloudflare

# TypeScript
npm run cf-typegen  # Generate binding types

Critical Configuration

// wrangler.jsonc
{
  "compatibility_date": "2025-05-05",  // Minimum!
  "compatibility_flags": ["nodejs_compat"]  // Required!
}

Common Pitfalls

❌ Using Edge runtime → ✅ Use Node.js runtime
❌ Global DB clients → ✅ Request-scoped clients
❌ Old compatibility_date → ✅ Use 2025-05-05+
❌ Missing nodejs_compat → ✅ Add to compatibility_flags
❌ Only testing in dev → ✅ Always test preview before deploy
❌ Using Turbopack → ✅ Use standard Next.js build

Production Tested : Official Cloudflare support and active community Token Savings : ~59% vs manual setup Errors Prevented : 10+ documented issues Last Verified : 2025-10-21

Weekly Installs

Repository

jackspace/claudeskillz

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykPass

Installed on

opencode63

gemini-cli62

codex58

cursor54

github-copilot51

claude-code49

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

145,500 周安装

运行时	Node.js 或 Edge	Node.js（通过 nodejs_compat）
开发服务器	`next dev`	`next dev` + `opennextjs-cloudflare preview`
部署	平台特定	`opennextjs-cloudflare deploy`
Worker 大小	无限制	3 MiB（免费）/ 10 MiB（付费）
数据库连接	全局客户端可用	必须是请求作用域
图片优化	内置	通过 Cloudflare Images
缓存	Next.js 缓存	OpenNext 配置 + Workers 缓存

Cloudflare Next.js部署指南：使用OpenNext适配器将Next.js应用部署到Workers

🇨🇳中文介绍

Cloudflare Next.js 部署技能

使用场景

核心概念

OpenNext 适配器架构

与标准 Next.js 的关键区别

相关 Skills

设置模式

新项目设置

现有项目迁移

1. 安装适配器

2. 创建 wrangler.jsonc

3. 创建 open-next.config.ts

4. 更新 package.json 脚本

5. 确保使用 Node.js 运行时（而非 Edge）

开发工作流

双重测试策略

何时使用

配置要求

Wrangler 配置

包导出的环境变量

Cloudflare 绑定集成

错误预防（10+ 个已记录的错误）

1. Worker 大小限制超出（3 MiB - 免费计划）

2. Worker 大小限制超出（10 MiB - 付费计划）

3. FinalizationRegistry 未定义

4. 无法代表不同请求执行 I/O

5. NPM 包导入失败

6. 加载块失败（Turbopack）

7. SSRF 漏洞（CVE-2025-6087）

8. Durable Objects 绑定警告

9. Prisma + D1 中间件冲突

10. cross-fetch 库错误

11. Windows 开发问题

功能支持矩阵

与 Cloudflare 服务集成

D1 数据库（SQL）

R2 存储（对象存储）

Workers AI（模型推理）

KV 存储（键值）

图片优化

缓存配置

已知限制

尚未支持

Worker 大小约束

数据库连接

部署

从本地机器部署

从 CI/CD 部署

自定义域名

TypeScript 支持

测试

本地测试（开发）

本地测试（类生产环境）

集成测试

从其他平台迁移

从 Vercel 迁移

从 AWS / 其他平台迁移

资源

官方文档

故障排除

相关技能

快速参考

基本命令

关键配置

常见陷阱