⚡

CloudflareNext.js部署技能 cloudflare-nextjs

这个技能用于将Next.js应用程序部署到Cloudflare Workers，通过OpenNext适配器实现服务器端渲染（SSR）、静态站点生成（SSG）、增量静态再生（ISR）等功能。它支持App Router和Pages Router，适用于生产级服务器less托管，便于迁移现有应用或构建新项目。关键词：Cloudflare Next.js, OpenNext Cloudflare, 部署, 服务器less, SSR, ISR, 前端开发

Serverless 0 次安装 0 次浏览 更新于 3/8/2026

名称: cloudflare-nextjs 描述: 通过OpenNext适配器将Next.js部署到Cloudflare Workers。用于SSR、ISR、App/Pages Router，或遇到Worker大小限制、运行时兼容性、连接作用域错误时。

关键词: Cloudflare Next.js, OpenNext Cloudflare, @opennextjs/cloudflare, Next.js Workers, Next.js App Router Cloudflare, Next.js Pages Router Cloudflare, Next.js SSR Cloudflare, Next.js ISR, 服务器组件cloudflare, 服务器操作cloudflare, Next.js 中间件workers, nextjs d1, nextjs r2, nextjs kv, Next.js 部署, opennextjs-cloudflare cli, nodejs_compat, worker大小限制, next.js运行时兼容性, 数据库连接作用域, Next.js迁移cloudflare 许可证: MIT 元数据: 版本: 1.0.0 最后验证: 2025-11-21 包版本: “@opennextjs/cloudflare”: “^1.13.1” “next”: “^14.2.0 || ^15.0.0 || ^16.0.0” “wrangler”: “^4.50.0” 兼容性要求: 兼容日期: “2025-05-05” 兼容标志: [“nodejs_compat”] 令牌节省: “~59%” 预防错误: 10 官方文档: “https://opennext.js.org/cloudflare” Cloudflare指南: “https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/”

Cloudflare Next.js 部署技能

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

何时加载参考文件

根据具体任务加载额外参考文件：

  • references/error-catalog-extended.md - 在设置、构建或部署期间遇到任何错误时加载。包含11+个记录问题的完整目录，包括根本原因、解决方案和官方来源。

  • references/service-integration-patterns.md - 在将Cloudflare服务（D1、R2、KV、Workers AI）与Next.js集成时加载。包含数据库查询、文件上传、缓存和AI推理的完整模式。

  • references/troubleshooting.md - 加载以获取错误目录之外的通用故障排除和调试指南。

  • references/feature-support.md - 在检查特定Next.js功能是否在Cloudflare Workers上受支持时加载（例如，“我能使用服务器操作吗？”，“ISR有效吗？”）。

  • references/database-client-example.ts - 在集成外部数据库客户端（Drizzle、Prisma、PostgreSQL、MySQL）并需要Workers要求的正确请求作用域模式时加载。

  • references/open-next.config.ts - 在配置缓存行为、图像优化或自定义OpenNext设置时加载。

  • references/package.json - 在设置新项目或将现有Next.js应用程序迁移到Cloudflare Workers时加载。

  • references/wrangler.jsonc - 在配置Worker设置、兼容标志、环境绑定（D1、R2、KV、AI）或部署选项时加载。

使用此技能时

  • 将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网络进行全球边缘部署

与标准Next.js的关键区别

OpenNext适配器将Next.js构建转换为Workers。关键要求：

  • 通过nodejs_compat标志的Node.js运行时（非Edge）
  • 请求作用域的数据库客户端（全局客户端失败）
  • Worker大小限制：3 MiB（免费）/ 10 MiB（付费）
  • 双重测试：next dev用于速度，preview用于生产类验证

设置模式

新项目设置

使用Cloudflare的create-cloudflare（C3）CLI来搭建预配置为Workers的新Next.js项目：

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

这做什么：

  1. 运行Next.js官方设置工具（create-next-app）
  2. 安装@opennextjs/cloudflare适配器
  3. 创建正确配置的wrangler.jsonc
  4. 创建用于缓存配置的open-next.config.ts
  5. 将部署脚本添加到package.json
  6. 可选地立即部署到Cloudflare

开发工作流：

npm run dev      # Next.js开发服务器（快速重新加载）
npm run preview  # 在workerd运行时中测试（生产类）
npm run deploy   # 构建并部署到Cloudflare

现有项目迁移

将OpenNext适配器添加到现有Next.js应用程序：

1. 安装适配器

bun add -d @opennextjs/cloudflare

2. 创建 wrangler.jsonc

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

关键配置：

  • compatibility_date: 最低2025-05-05（用于FinalizationRegistry支持）
  • compatibility_flags: 必须包括nodejs_compat（用于Node.js运行时）

3. 创建 open-next.config.ts

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

export default defineCloudflareConfig({
  // 缓存配置（可选）
  // 参见：https://opennext.js.org/cloudflare/caching
});

4. 更新 package.json 脚本

{
  "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"
  }
}

脚本目的：

  • dev: Next.js开发服务器（快速迭代）
  • preview: 构建 + 在workerd运行时中运行（部署前测试）
  • deploy: 构建 + 部署到Cloudflare
  • cf-typegen: 为Cloudflare绑定生成TypeScript类型

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

从应用中移除Edge运行时导出：

// ❌ 移除这个（Edge运行时不支持）
export const runtime = "edge";

// ✅ 使用Node.js运行时（默认）
// 无需导出 - Node.js是默认的

开发工作流

需要双重测试：

  • npm run dev - 快速迭代（Next.js开发服务器）
  • npm run preview - 生产类测试（workerd运行时，部署前必须测试）
  • npm run deploy - 构建并部署

关键：部署前始终测试preview以捕获Workers特定运行时问题

关键配置

wrangler.jsonc最低要求：

{
  "compatibility_date": "2025-05-05",  // FinalizationRegistry的最低要求
  "compatibility_flags": ["nodejs_compat"]  // Node.js运行时必需
}

Cloudflare绑定：在wrangler.jsonc中添加D1、R2、KV或AI绑定，通过process.env访问（见“Cloudflare服务集成”部分获取完整模式）

包导出（如果需要）：创建.env，设置WRANGLER_BUILD_PLATFORM="node"以优先Node.js导出

前5个关键错误

这些是最常见的部署阻塞错误。获取11+个错误的完整目录，加载references/error-catalog-extended.md。

1. Worker大小限制超出

错误: "您的Worker超出了3 MiB的大小限制"（免费）或"10 MiB"（付费）

快速修复: 升级计划，使用bunx opennextjs-cloudflare build分析捆绑包 → 检查.open-next/server-functions/default/handler.mjs.meta.json，移除未使用的依赖项，或使用动态导入。

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

2. 无法为不同请求执行I/O

错误: "无法为不同请求执行I/O"

原因: 全局数据库客户端跨请求重用（Workers限制）

快速修复: 在请求处理器内部创建数据库客户端，绝不全局。或使用专为Workers设计的Cloudflare D1。

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

// ✅ 正确: 请求作用域
export async function GET() {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  // ... 使用pool
  await pool.end();
}

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

3. NPM包导入失败

错误: "无法解析'<package>'"

快速修复: 在wrangler.jsonc中启用nodejs_compat标志，和/或创建.env，设置WRANGLER_BUILD_PLATFORM="node"。

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

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

漏洞: 通过/_next/image端点的服务器端请求伪造，版本< 1.3.0

快速修复: 立即升级: bun add -d @opennextjs/cloudflare@^1.3.0

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

5. 加载块失败（Turbopack）

错误: "加载块服务器/chunks/ssr/失败"

快速修复: 从构建命令中移除--turbo标志。使用next build（标准），不是next build --turbo。

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

更多错误: 加载references/error-catalog-extended.md获取6个额外记录错误，包括FinalizationRegistry问题、Durable Objects警告、Prisma冲突、cross-fetch错误和Windows开发问题

功能支持矩阵

功能 状态 备注
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运行时

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

Cloudflare服务集成

通过process.env在Next.js路由处理器中访问Cloudflare绑定：

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

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

  // D1数据库
  const users = 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 ai = await env.AI.run('@cf/meta/llama-3-8b-instruct', { prompt: 'Hello' });

  return Response.json({ users, file, value, ai });
}

Wrangler绑定配置:

{
  "d1_databases": [{ "binding": "DB", "database_id": "..." }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "..." }],
  "kv_namespaces": [{ "binding": "KV", "id": "..." }],
  "ai": { "binding": "AI" }
}

详细集成模式: 加载references/service-integration-patterns.md获取完整模式，包括：

  • D1: 查询、插入、事务、批量操作
  • R2: 上传、下载、列表、删除与流式传输
  • KV: 获取、设置TTL、删除、列出键
  • Workers AI: 文本生成、嵌入、图像分类
  • 多服务集成示例
  • 绑定的TypeScript类型（npm run cf-typegen）

相关技能: cloudflare-d1、cloudflare-r2、cloudflare-kv、cloudflare-workers-ai用于服务特定深入探讨

图像优化与缓存

图像: 通过Cloudflare Images自动优化（单独计费）。在open-next.config.ts中配置imageOptimization: { loader: 'cloudflare' }。使用标准Next.js <Image />组件。

缓存: OpenNext提供合理的默认值。如果需要，在open-next.config.ts中覆盖。参见 https://opennext.js.org/cloudflare/caching 获取高级配置

已知限制

尚不支持

  1. Node.js中间件（Next.js 15.2+）

    • 在Next.js 15.2中引入
    • 未来发布支持计划
    • 现在使用标准中间件

  2. Edge运行时

    • 仅支持Node.js运行时
    • 从应用中移除export const runtime = "edge"

  3. 完整Windows支持

    • Windows开发不完全保证
    • 使用WSL、VM或基于Linux的CI/CD

Worker大小约束

  • 免费计划: 3 MiB限制（gzip压缩）
  • 付费计划: 10 MiB限制（gzip压缩）
  • 开发期间监控捆绑包大小
  • 使用动态导入进行代码拆分

数据库连接

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

部署

本地: npm run deploy（构建并部署）

CI/CD: 在GitHub Actions、GitLab CI或Cloudflare Workers Builds中使用npm run deploy命令（自动检测）

自定义域: Workers & Pages → Settings → Domains & Routes（域必须在Cloudflare上）

TypeScript与测试

TypeScript类型: 运行npm run cf-typegen生成带有类型绑定的cloudflare-env.d.ts（D1Database、R2Bucket、KVNamespace、Ai）

测试: 部署前始终在preview模式中测试，以捕获Workers特定运行时问题并验证绑定工作正常

从其他平台迁移

从Vercel迁移

  1. 复制现有Next.js项目
  2. 运行现有项目迁移步骤（如上）
  3. 在Cloudflare仪表板中更新环境变量
  4. 替换Vercel特定功能：
    • Vercel Postgres → Cloudflare D1
    • Vercel Blob → Cloudflare R2
    • Vercel KV → Cloudflare KV
    • Vercel Edge Config → Cloudflare KV
  5. 使用npm run preview彻底测试
  6. 使用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"]  // 必需！
}

常见陷阱

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

生产测试: 官方Cloudflare支持和活跃社区 令牌节省: ~59%对比手动设置 预防错误: 11+个记录问题 最后验证: 2025-12-04