# 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 开发服务器和工作运行时进行测试 * **自定义构建管道**：`下一个构建` → OpenNext 转换 → Worker 部署 * **Cloudflare 特定配置**：需要 wrangler.jsonc 和 open-next.config.ts ### 与标准 Next.js 的关键区别方面|标准 Next.js | Cloudflare 工人 ---|---|--- 运行时 | Node.js 或 Edge | Node.js（通过nodejs_compat）开发服务器 | `下一个开发人员` | `next dev` \+ `opennextjs-cloudflare 预览` 部署|平台特定 | `opennextjs-cloudflare 部署` 工人尺寸|无限制| 3 MiB（免费）/10 MiB（付费）数据库连接 |全球客户OK |必须是请求范围内的图像优化|内置|通过 Cloudflare 图片缓存 | Next.js 缓存 | OpenNext 配置 + Workers 缓存 ## 设置模式 ### 新项目设置使用 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\.安装适配器 npm install --save-dev @opennextjs/cloudflare #### 2\.创建 wrangler.jsonc { “名称”：“我的下一个应用程序”， “兼容性日期”：“2025-05-05”， “compatibility_flags”：[“nodejs_compat”] } **关键配置**： * `compatibility_date`: **最小`2025-05-05`** （用于 FinalizationRegistry 支持） * `compatibility_flags`: **必须包含`nodejs_compat`**（对于 Node.js 运行时） #### 3\.创建 open-next.config.ts 从“@opennextjs/cloudflare”导入{defineCloudflareConfig}；导出默认的defineCloudflareConfig({ // 缓存配置（可选） // 请参阅：https://opennext.js.org/cloudflare/caching }); #### 4\.更新 package.json 脚本 { “脚本”：{ “dev”：“下一个开发者”， “构建”：“下一个构建”， "preview": "opennextjs-cloudflare 构建 && opennextjs-cloudflare 预览", "deploy": "opennextjs-cloudflare 构建 && opennextjs-cloudflare 部署", "cf-typegen": "牧马人类型 --env-interface CloudflareEnv cloudflare-env.d.ts" } } **脚本目的**： * `dev`：Next.js 开发服务器（快速迭代） * `preview`：在workerd运行时构建+运行（部署前测试） * `deploy`：构建 + 部署到 Cloudflare * `cf-typegen`：为 Cloudflare 绑定生成 TypeScript 类型 #### 5\.确保 Node.js 运行时（不是 Edge）从您的应用程序中删除 Edge 运行时导出： // ❌ 删除此内容（不支持 Edge 运行时）导出常量运行时=“边缘”； // ✅ 使用 Node.js 运行时（默认） // 无需导出 - 默认为 Node.js ## 开发工作流程 ### 双重测试策略 **始终在两种环境中进行测试**： 1. **Next.js 开发服务器** (`npm run dev`) * 快速热重载 * 最佳开发者体验 * 在 Node.js 中运行（不是生产运行时） * 用于快速迭代 2. **Workerd 运行时**（`npm 运行预览`） * 在类似生产环境中运行 * 捕获运行时特定的问题 * 重建时间较慢 * **部署前需要** ### 何时使用每个 # 迭代 UI/逻辑 → 使用 Next.js 开发服务器 npm 运行开发 # 测试集成（D1、R2、KV）→ 使用预览 npm 运行预览 # 部署之前 → 始终测试预览 npm 运行预览 # 部署到生产环境 npm 运行部署 ## 配置要求 ### 牧马人配置 **“wrangler.jsonc”中的最低要求**： { “名称”：“您的应用程序名称”， "compatibility_date": "2025-05-05", // FinalizationRegistry 的最小值 "compatibility_flags": ["nodejs_compat"] // Node.js 运行时必需的 } ### 包导出的环境变量如果使用具有多个导出条件的 npm 包，请创建 `.env`： WRANGLER_BUILD_CONDITIONS="" WRANGLER_BUILD_PLATFORM =“节点” 这可确保 Wrangler 在可用时优先考虑“节点”导出。 ### Cloudflare 绑定集成在 `wrangler.jsonc` 中添加绑定： { “名称”：“您的应用程序名称”， “兼容性日期”：“2025-05-05”， “compatibility_flags”：[“nodejs_compat”]， // D1 数据库 “d1_数据库”：[ { “绑定”：“数据库”， "database_name": "生产数据库", "database_id": "您的数据库 ID" } ], // R2 存储 “r2_buckets”：[ { “绑定”：“桶”， "bucket_name": "你的存储桶" } ], // KV存储 “kv_命名空间”：[ { “绑定”：“KV”， "id": "你的 kv-id" } ], // 工人人工智能 “艾”：{ “绑定”：“人工智能” } } 通过“process.env”访问 Next.js 中的绑定： // 应用程序/api/route.ts 从 'next/server' 导入类型 { NextRequest }；导出异步函数 GET(请求: NextRequest) { // 访问 Cloudflare 绑定 const env = process.env 为任意； // D1数据库查询 const result = wait env.DB.prepare('SELECT * FROM users').all(); // R2 存储访问 const file = wait env.BUCKET.get('file.txt'); // KV存储访问 const value = wait env.KV.get('key'); // Workers AI推理 const 响应 = 等待 env.AI.run('@cf/meta/llama-3-8b-instruct', { 提示：“你好人工智能” }); 返回 Response.json({ 结果 }); } ## 错误预防（10 多个已记录的错误） ### 1\.超出工作线程大小限制（3 MiB - 免费计划） **错误**：`“您的 Worker 超出了 3 MiB 的大小限制”` **原因**：Workers 免费计划将 Worker 大小限制为 3 MiB（gzip 压缩） **解决方案**： * 升级到员工付费计划（10 MiB 限制） * 分析包大小并删除未使用的依赖项 * 使用动态导入来对大型依赖项进行代码分割 **捆绑分析**： npx opennextjs-cloudflare 构建 cd .open-next/服务器功能/默认 # 使用 ESBuild Bundle Analyzer 分析 handler.mjs.meta.json **来源**： ** ** ### 2\.超出工作线程大小限制（10 MiB - 付费计划） **错误**：`“您的 Worker 超出了 10 MiB 的大小限制”` **原因**：不必要的代码捆绑到 Worker 中 **调试工作流程**： 1.运行“npx opennextjs-cloudflare build” 2. 导航到“.open-next/server-functions/default” 3. 使用 ESBuild Bundle Analyzer 分析 `handler.mjs.meta.json` 4. 识别并删除/外部化大型依赖项 **来源**： ** ** ### 3\. FinalizationRegistry 未定义 **错误**：`“ReferenceError：FinalizationRegistry 未定义”` **原因**：wrangler.jsonc 中的 `compatibility_date` 太旧 **解决方案** ：将 `compatibility_date` 更新为 `2025-05-05` 或更高版本： { "compatibility_date": "2025-05-05" // FinalizationRegistry 的最小值 } **来源**： ** ** ### 4\.无法代表不同请求执行 I/O **错误**：`“无法代表不同的请求执行 I/O”` **原因**：数据库客户端全局创建并跨请求重用 **问题代码**： // ❌ 错误：全局数据库客户端从'pg'导入{池}； const pool = new Pool({ connectionString: process.env.DATABASE_URL }); 导出异步函数 GET() { // 这将失败 - 在不同的请求上下文中创建的池 const result = wait pool.query('SELECT * FROM users'); 返回 Response.json(结果); } **解决方案**：在请求处理程序中创建数据库客户端： // ✅ 正确：请求范围的数据库客户端从'pg'导入{池}；导出异步函数 GET() { // 在请求上下文中创建客户端 const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const result = wait pool.query('SELECT * FROM users'); 等待池.end(); 返回 Response.json(结果); } **替代**：使用 Cloudflare D1（专为 Workers 设计）而不是外部数据库： // ✅ 最佳：使用 D1（不需要连接池）导出异步函数 GET(请求: NextRequest) { const env = process.env 为任意； const result = wait env.DB.prepare('SELECT * FROM users').all(); 返回 Response.json(结果); } **来源**： ** ** ### 5\. NPM包导入失败 **错误**：`“无法解析''”` **原因**：缺少 `nodejs_compat` 标志或包导出条件 **解决方案 1**：启用 `nodejs_compat` 标志： { “compatibility_flags”：[“nodejs_compat”] } **解决方案 2** ：对于具有多个导出的包，创建 `.env`： WRANGLER_BUILD_CONDITIONS="" WRANGLER_BUILD_PLATFORM =“节点” **来源**： ** ** ### 6\.无法加载块（Turbopack） **错误**：`“无法加载块服务器/块/ssr/”` **原因**：使用 Turbopack 构建的 Next.js (`next build --turbo`) **解决方案**：使用标准构建（适配器不支持 Turbopack）： { “脚本”：{ "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\.耐用物体绑定警告 **警告**：“您已经定义了对以下内部持久对象的绑定...在本地开发中不起作用，但它们应该在生产中起作用”` **原因**：OpenNext 使用持久对象进行缓存（`DOQueueHandler`、`DOShardedTagCache`） **解决方案**：**可以安全地忽略** \- 警告是预期行为 **替代**（抑制警告）：使用自己的配置在单独的 Worker 中定义持久对象 **来源**： ** ** ### 9\. Prisma + D1 中间件冲突 **错误** ：在 Next.js 中间件中使用 `@prisma/client` \+ `@prisma/adapter-d1` 时出现构建错误 **原因**：中间件上下文中的数据库初始化 **解决方法**：在路由处理程序中初始化 Prisma 客户端，而不是中间件 **来源**： ** ** ### 10\.交叉获取库错误 **错误**：使用依赖于“cross-fetch”的库时出现错误 **原因**：OpenNext 修补部署包导致“交叉获取”在本机获取可用时尝试使用 Node.js 库 **解决方案**：直接使用原生 `fetch` API 而不是 `cross-fetch`： // ✅ 使用原生获取 const 响应 = 等待 fetch('https://api.example.com/data'); // ❌ 避免交叉获取 // 从 'cross-fetch' 导入 fetch; **来源**： ** ** ### 11\. Windows 开发问题 **问题**：不保证完整的 Windows 支持 **原因**：Windows 上的底层 Next.js 工具问题 **解决方案**： * 使用 WSL（适用于 Linux 的 Windows 子系统） * 使用Linux虚拟机 * 使用基于Linux的CI/CD进行部署 **来源**： ## 功能支持矩阵特色 |状态 |注释 ---|---|--- **应用程序路由器** | ✅ 全力支持 |最新的应用程序路由器功能可以使用 **页面路由器** | ✅ 全力支持 |支持旧版页面路由器 **路线处理程序** | ✅ 全力支持 | API 路由按预期工作 **React 服务器组件** | ✅ 全力支持 | RSC 功能齐全 **服务器操作** | ✅ 全力支持 |服务器操作工作 **SSG** | ✅ 全力支持 |静态站点生成 **SSR** | ✅ 全力支持 |服务器端渲染 **情监侦** | ✅ 全力支持 |增量静态再生 **中间件** | ✅ 支持 | Node.js 中间件除外（15.2+） **图像优化** | ✅ 支持 |通过 Cloudflare 图片 **部分预渲染 (PPR)** | ✅ 支持 |在 Next.js 中进行实验 **可组合缓存** | ✅ 支持 | “使用缓存”指令 **响应流** | ✅ 支持 |流式响应有效 **`下一个/之后` API** | ✅ 支持 |响应后异步工作 **Node.js 中间件 (15.2+)** | ❌ 不支持 |计划未来的支持 **边缘运行时** | ❌ 不支持 |使用 Node.js 运行时 **来源**： ## 与 Cloudflare 服务集成 ### D1 数据库 (SQL) // 应用程序/api/users/route.ts 从 'next/server' 导入类型 { NextRequest }；导出异步函数 GET(请求: NextRequest) { const env = process.env 为任意； const 结果 = 等待 env.DB.prepare( '从用户中选择 * WHERE active = ?' ).bind(true).all(); 返回 Response.json(结果.结果); } 导出异步函数 POST(request: NextRequest) { const env = process.env 为任意； const { 姓名，电子邮件 } = wait request.json(); const 结果 = 等待 env.DB.prepare( '插入用户（姓名、电子邮件）值 (?, ?)' ).bind(姓名、电子邮件).run(); 返回 Response.json({ id: result.meta.last_row_id }); } **牧马人配置**： { “d1_数据库”：[ { “绑定”：“数据库”， "database_name": "生产数据库", "database_id": "您的数据库 ID" } ] } **另请参阅**：完整 D1 模式的“cloudflare-d1”技能 ** ** ### R2 存储（对象存储） // 应用程序/api/upload/route.ts 从 'next/server' 导入类型 { NextRequest }；导出异步函数 POST(request: NextRequest) { const env = process.env 为任意； const formData = 等待 request.formData(); const file = formData.get('file') as File; //上传到R2 等待 env.BUCKET.put(file.name, file.stream(), { http元数据：{ contentType: 文件类型 } }); return Response.json({ success: true, filename: file.name }); } 导出异步函数 GET(请求: NextRequest) { const env = process.env 为任意； const { searchParams } = 新 URL(request.url); const 文件名 = searchParams.get('文件'); const object = wait env.BUCKET.get(文件名); 如果（！对象）{ return new Response('未找到', { status: 404 }); } 返回新的响应（对象.body，{ 标题：{ '内容类型'：object.httpMetadata?.contentType || '应用程序/八位字节流' } }); } **另请参阅**：完整 R2 模式的“cloudflare-r2”技能 ** ** ### Workers AI（模型推理） // 应用程序/api/ai/route.ts 从 'next/server' 导入类型 { NextRequest }；导出异步函数 POST(request: NextRequest) { const env = process.env 为任意； const { 提示 } = 等待 request.json(); const 响应 = 等待 env.AI.run('@cf/meta/llama-3-8b-instruct', { 提示 }); 返回 Response.json(响应); } **牧马人配置**： { “艾”：{ “绑定”：“人工智能” } } **另请参阅**：完整 AI 模式的“cloudflare-workers-ai”技能 ** ** ### KV存储（键值） // 应用程序/api/cache/route.ts 从 'next/server' 导入类型 { NextRequest }；导出异步函数 GET(请求: NextRequest) { const env = process.env 为任意； const { searchParams } = 新 URL(request.url); const key = searchParams.get('key'); const value = wait env.KV.get(key); 返回 Response.json({ 键, 值 }); } 导出异步函数 PUT(请求: NextRequest) { const env = process.env 为任意； const { key, value, ttl } = wait request.json(); 等待 env.KV.put(key, value, {expirationTtl: ttl }); 返回 Response.json({ 成功: true }); } **另请参阅**：完整 KV 模式的“cloudflare-kv”技能 ## 图像优化 Next.js 图像优化通过 Cloudflare Images 进行。在`open-next.config.ts`中配置：从“@opennextjs/cloudflare”导入{defineCloudflareConfig}；导出默认的defineCloudflareConfig({ 图像优化：{ 加载器：'cloudflare' } }); 在组件中的用法：从“下一个/图像”导入图像；导出默认函数 Avatar() { 返回（ <图片 src="/头像.jpg" alt="用户头像" 宽度={200} 高度={200} // 通过 Cloudflare Images 自动优化 /> ）； } **计费**：Cloudflare Images 使用单独计费 **文档**： ## 缓存配置在 `open-next.config.ts` 中配置缓存行为：从“@opennextjs/cloudflare”导入{defineCloudflareConfig}；导出默认的defineCloudflareConfig({ // 自定义缓存配置缓存：{ // 覆盖默认缓存行为 // 请参阅：https://opennext.js.org/cloudflare/caching } }); **默认行为**：OpenNext 提供合理的缓存默认值 **高级用法**：请参阅官方 OpenNext 缓存文档 ## 已知限制 ### 尚不支持 1. **Node.js 中间件 (Next.js 15.2+)** * 在 Next.js 15.2 中引入 * 计划在未来版本中提供支持 * 暂时使用标准中间件 2. **边缘运行时** * 仅支持 Node.js 运行时 * 从您的应用程序中删除 `export const runtime = "edge"` 3. **完整的Windows支持** * 不完全保证 Windows 上的开发 * 使用 WSL、VM 或基于 Linux 的 CI/CD ### 工作人员规模限制 * **免费计划**：3 MiB 限制（gzip 压缩） * **付费计划**：10 MiB 限制（gzip 压缩） * 在开发过程中监控包大小 * 使用动态导入进行代码分割 ### 数据库连接 * 外部数据库客户端（PostgreSQL、MySQL）必须是请求范围的 * 无法跨请求重用连接（Workers 限制） * 优先选择 Cloudflare D1 来满足数据库需求（专为 Workers 设计） ## 部署 ### 从本地计算机部署 # 在一个命令中构建和部署 npm 运行部署 # 或者一步一步： npx opennextjs-cloudflare 构建 npx opennextjs-cloudflare 部署 ### 从 CI/CD 部署在 CI/CD 系统中配置部署命令： npm 运行部署 **示例**： * GitHub 操作：`.github/workflows/deploy.yml` * GitLab CI：`.gitlab-ci.yml` * Cloudflare Workers 构建：自动检测“npm run deploy” **环境变量** ：在 Cloudflare 仪表板或 CI/CD 系统中设置机密 ### 自定义域在 Cloudflare 仪表板中添加自定义域： 1. 导航至工作人员和页面 2. 选择您的工人 3. 设置 → 域名和路由 4.添加自定义域名 **DNS**：域名必须位于 Cloudflare 上（需要区域） ## TypeScript 支持生成 Cloudflare 绑定的类型： npm 运行 cf-typegen 使用绑定类型创建“cloudflare-env.d.ts”： // cloudflare-env.d.ts（自动生成）接口 CloudflareEnv { DB：D1数据库；桶：R2桶； KV：KV命名空间；人工智能：艾； } 在路由处理程序中使用：从 'next/server' 导入类型 { NextRequest }；导出异步函数 GET(请求: NextRequest) { const env = process.env 作为 CloudflareEnv； // 现在输入env.DB、env.BUCKET等 } ## 测试 ### 本地测试（开发） # Next.js 开发服务器（快速迭代） npm 运行开发 ### 本地测试（类似生产） # Workerd 运行时（捕获 Workers 特定问题） npm 运行预览 ### 集成测试在部署之前始终在“预览”模式下进行测试： # 在workerd中构建并运行 npm 运行预览 # 测试绑定（D1、R2、KV、AI） # 测试中间件 # 测试API路由 # 测试 SSR/ISR 行为 ## 从其他平台迁移 ### 来自维塞尔 1.复制现有的Next.js项目 2. 运行现有项目迁移步骤（上文） 3. 在 Cloudflare 仪表板中更新环境变量 4. 替换 Vercel 特定功能： * Vercel Postgres → Cloudflare D1 * Vercel Blob → Cloudflare R2 * Vercel KV → Cloudflare KV * Vercel 边缘配置 → Cloudflare KV 5. 使用“npm run Preview”进行彻底测试 6. 使用“npm run deploy”进行部署 ### 来自 AWS/其他平台与 Vercel 迁移过程相同 - 适配器自动处理 Next.js 标准功能。 ## 资源 ### 官方文档 * **OpenNext Cloudflare** ： * **Cloudflare Next.js 指南**： * **Next.js 文档**： ### 故障排除 * **故障排除指南**： * **已知问题**： * **GitHub 问题**： ### 相关技能 * `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 # 打字稿 npm run cf-typegen # 生成绑定类型 ### 关键配置 // 牧马人.jsonc { "compatibility_date": "2025-05-05", // 最小值！ "compatibility_flags": ["nodejs_compat"] // 必需！ } ### 常见陷阱 1. ❌ 使用 Edge 运行时 → ✅ 使用 Node.js 运行时 2. ❌ 全局数据库客户端 → ✅ 请求范围的客户端 3. ❌旧的compatibility_date → ✅ 使用2025-05-05+ 4. ❌ 缺少nodejs_compat → ✅ 添加到compatibility_flags 5. ❌ 仅在 `dev` 中进行测试 → ✅ 在部署之前始终测试 `preview` 6. ❌ 使用 Turbopack → ✅ 使用标准 Next.js 构建 ** ** **生产测试**：官方 Cloudflare 支持和活跃社区 **令牌节省**：与手动设置相比，约 59% **预防错误**：10 多个已记录的问题 **最后验证**：2025 年 10 月 21 日

Cloudflare Nextjs

包含技能