将 Next.js 部署到 Cloudflare Workers

Cloudflare Workers 不仅能运行轻量级边缘函数，也可以承载完整的 Next.js 应用。借助 Cloudflare OpenNext 适配器，App Router、Pages Router、SSR、SSG、ISR、Server Actions、React Server Components 和响应流等常用能力都可以部署到 Workers。

本文将使用 pnpm 完成以下工作：

• 创建一个已经配置好 Cloudflare 的 Next.js 项目
• 在 Next.js 开发服务器中进行本地开发
• 在与生产环境更接近的 Workers Runtime 中预览应用
• 将应用部署到 workers.dev
• 将已有的 Next.js 项目迁移到 Cloudflare Workers

本文参考 Cloudflare 官方 Next.js 指南 编写，命令与配置以 2026 年 7 月为基准。

一、准备工作

开始前，请准备：

• 一个 Cloudflare 账户
• Node.js 的当前 LTS 版本
• pnpm

运行下面的命令检查本地环境：

node --version
pnpm --version

如果系统尚未启用 pnpm，可以通过 Node.js 自带的 Corepack 安装：

corepack enable
corepack prepare pnpm@latest --activate

二、创建新的 Next.js 项目

Cloudflare 提供了 create-cloudflare（简称 C3）脚手架。它会调用 Next.js 官方的 create-next-app，随后自动加入 OpenNext 和 Wrangler 所需的配置。

运行：

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

执行过程中，CLI 会询问 Next.js 项目选项。对于新项目，可以选择 TypeScript、ESLint、Tailwind CSS 和 App Router。CLI 最后还会询问是否立即部署；第一次操作时可以先选择不部署，等本地验证完成后再手动发布。

进入项目目录：

cd my-next-app

此时项目中除了常规的 Next.js 文件，还应包含 Cloudflare 相关配置，例如：

my-next-app/
├── app/
├── public/
├── open-next.config.ts
├── package.json
├── next.config.ts
└── wrangler.jsonc

实际文件名可能随 Next.js 与脚手架版本变化，但 open-next.config.ts、Wrangler 配置以及 package.json 中的 Cloudflare 脚本是后续部署的关键。

三、本地开发

启动 Next.js 开发服务器：

pnpm run dev

终端会显示本地地址，通常为：

http://localhost:3000

在浏览器中打开该地址，即可看到 Next.js 初始页面。修改 app/page.tsx 后，页面会自动刷新。

这里运行的是 Node.js 中的 Next.js 开发服务器。它启动快、热更新体验好，适合日常编码，但并不等同于应用部署后的实际运行环境。

四、在 Workers Runtime 中预览

部署到 Cloudflare 后，应用运行于 workerd，而不是本地 Node.js。为了提前发现运行时兼容性、绑定或构建产物方面的问题，应在发布前执行：

pnpm run preview

该脚本通常会依次完成两件事：

1. 使用 OpenNext 将 Next.js 应用构建为 Workers 可运行的产物。
2. 使用 wrangler dev 在本地启动 Workers Runtime。

根据终端输出打开预览地址，再检查页面、Route Handler、Server Action 和服务端渲染功能是否正常。

简单来说：

不能只依赖 dev 的结果判断线上一定可用。涉及 Node.js API、环境变量或 Cloudflare 绑定时，preview 的验证尤其重要。

五、登录 Cloudflare 并部署

如果尚未通过 Wrangler 登录 Cloudflare，运行：

pnpm wrangler login

浏览器会打开 Cloudflare 授权页面。确认授权后返回终端。

执行部署：

pnpm run deploy

OpenNext 会先构建应用，Wrangler 随后上传 Worker 和静态资源。成功后，终端会输出一个 workers.dev 地址，例如：

https://my-next-app.<your-subdomain>.workers.dev

打开该地址并检查线上页面：

后续每次发布新版本，只需再次运行：

pnpm run deploy

六、关键配置是如何工作的

由 C3 创建的项目通常已经配置完成，但理解下面几个文件有助于后续排错和扩展。

1. Wrangler 配置

典型的 wrangler.jsonc 如下：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "main": ".open-next/worker.js",
  "name": "my-next-app",
  "compatibility_date": "2026-07-28",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}

几个关键字段的含义如下：

• main：OpenNext 构建出的 Worker 入口。
• compatibility_date：Workers Runtime 的兼容性日期。新项目应使用创建或更新项目时的当前日期。
• nodejs_compat：启用 Workers 对一组 Node.js API 的兼容支持。OpenNext 要求兼容性日期不早于 2024-09-23。
• assets.directory：OpenNext 输出的静态资源目录。
• assets.binding：Worker 访问静态资源时使用的绑定名称。

2. OpenNext 配置

最小的 open-next.config.ts 内容为：

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

export default defineCloudflareConfig();

基础项目不需要继续修改。需要自定义缓存策略时，再参考 OpenNext Cloudflare 缓存文档。

3. package.json 脚本

Cloudflare 部署所需的核心脚本通常为：

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

其中 cf-typegen 会根据 Wrangler 配置生成 Cloudflare 环境和绑定的 TypeScript 类型：

pnpm run cf-typegen

当你在 Wrangler 配置中新增 KV、R2、D1 或其他绑定后，应重新执行该命令。

七、部署已有的 Next.js 项目

如果你已经有一个 Next.js 项目，可以先尝试 Wrangler 的自动配置功能，也可以手动完成接入。

方案 A：让 Wrangler 自动识别

在项目根目录运行：

pnpm wrangler deploy

如果项目中没有 Wrangler 配置，Wrangler 会检测 Next.js，并自动生成或补齐部署所需内容，包括：

• 安装或配置 @opennextjs/cloudflare
• 将 Worker 入口指向 .open-next/worker.js
• 将静态资源目录指向 .open-next/assets
• 启用 nodejs_compat
• 启用可观测性配置

自动配置适合快速迁移。完成后仍应检查生成的配置，并运行项目自己的测试与 pnpm run preview。

方案 B：手动接入 OpenNext

如果希望完全控制配置，请按照以下步骤操作。

第 1 步：安装依赖

pnpm add @opennextjs/cloudflare@latest
pnpm add -D wrangler@latest

第 2 步：创建 wrangler.jsonc

在项目根目录创建 wrangler.jsonc：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "main": ".open-next/worker.js",
  "name": "my-app",
  "compatibility_date": "2026-07-28",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}

将 name 改为你的 Worker 名称。它应使用小写字母、数字和连字符。

第 3 步：创建 OpenNext 配置

新建 open-next.config.ts：

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

export default defineCloudflareConfig();

第 4 步：更新 package.json

在 scripts 中加入：

{
  "scripts": {
    "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、build、start、lint 或 test 脚本，只需追加上面三项。

第 5 步：依次验证和部署

pnpm run dev
pnpm run preview
pnpm run deploy

建议严格按照这个顺序执行：先确认 Next.js 本身可开发运行，再确认 Workers Runtime 兼容，最后发布。

八、配置环境变量和密钥

Next.js 项目中的变量大致分为两类：

• NEXT_PUBLIC_...：可能在构建时被写入客户端 JavaScript，不能存放密钥。
• 非 NEXT_PUBLIC_...：仅供服务端代码使用，但仍需区分构建阶段与运行阶段。

本地开发可以继续使用 Next.js 支持的 .env.local。不要将包含密钥的环境文件提交到 Git。

运行时密钥可以使用 Wrangler 写入：

pnpm wrangler secret put API_TOKEN

随后根据提示输入密钥值。

如果使用 Workers Builds 或其他 CI/CD 服务，还要在构建平台中配置构建阶段所需的变量。原因是 Next.js 构建过程本身可能读取变量，用于生成静态页面、内联公开配置或执行其他构建逻辑。只配置 Worker 运行时变量并不一定足够。

九、绑定自定义域名

应用成功部署到 workers.dev 后，可以在 Cloudflare Dashboard 中进入对应 Worker，添加自定义域名或路由。

域名必须已经接入当前 Cloudflare 账户。配置完成并等待生效后，再通过正式域名检查页面、静态资源、重定向和服务端接口。

十、支持范围与注意事项

Cloudflare OpenNext 适配器支持大多数主流 Next.js 能力，包括：

• App Router 与 Pages Router
• Route Handlers
• React Server Components
• SSG、SSR 与 ISR
• Server Actions
• 响应流
• next/after 异步任务
• Middleware
• 通过 Cloudflare Images 实现的图像优化
• 实验性的 Partial Prerendering 与 use cache

需要特别注意：Next.js 15.2 引入的 Node.js Middleware 运行时目前尚未得到 Cloudflare 适配器支持。常规 Middleware 使用 Edge 兼容能力时不受这一限制。实验性 Next.js 功能的行为也可能随 Next.js 和适配器版本变化，升级前应先阅读版本说明并运行 pnpm run preview。

十一、常见问题

pnpm run dev 正常，但 pnpm run preview 失败

这通常表示代码依赖了 workerd 不支持或行为不同的 Node.js API。检查错误堆栈涉及的依赖，确认 nodejs_compat 已启用，并优先选择支持 Workers 或 Web 标准 API 的库。

提示找不到 .open-next/worker.js

该文件由 OpenNext 构建生成。不要直接执行原始的 wrangler deploy 配置路径；先运行：

pnpm exec opennextjs-cloudflare build

使用本文配置的项目则直接执行 pnpm run preview 或 pnpm run deploy，脚本会先构建。

线上读不到环境变量

检查变量是在构建阶段还是运行阶段使用。如果静态页面在构建时读取该变量，就必须在 CI/CD 的构建变量中配置；如果只在 Worker 请求处理阶段读取，则应配置 Worker 运行时变量或 Secret。

类型中没有新添加的 Cloudflare 绑定

修改 wrangler.jsonc 后重新生成类型：

pnpm run cf-typegen

图片优化行为与本地不同

Cloudflare 上的 Next.js 图片优化通过 Cloudflare Images 提供。确认账户和项目已经满足 Cloudflare Images 的使用要求，并在 Workers Runtime 预览及线上环境中分别验证。

十二、发布前检查清单

正式发布前，至少确认以下事项：

• pnpm run dev 可以正常启动
• 项目的 lint、类型检查和测试已通过
• pnpm run preview 中页面与服务端功能正常
• wrangler.jsonc 已启用 nodejs_compat
• compatibility_date 不早于 2024-09-23
• 构建变量与运行时 Secret 已分别配置
• 没有将 .env.local 或密钥提交到 Git
• pnpm run deploy 输出了有效的部署地址
• 线上环境中的页面、接口、静态资源和重定向均已验证

完成以上步骤后，你就拥有了一套完整的 Next.js on Cloudflare Workers 工作流：使用 Next.js 开发服务器获得高效的本地体验，通过 OpenNext 和 Wrangler 在 workerd 中进行生产前验证，最后将应用和静态资源一起部署到 Cloudflare 全球网络。

参考资料

• Cloudflare Workers：Next.js 指南
• OpenNext Cloudflare 适配器文档
• Wrangler 文档
• Workers Builds 文档
• Next.js 环境变量指南