跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

Next.js

最后更新 查看 MarkdownAgent 设置

从 CLI 开始 — 在 Workers 上搭建 Next.js 项目。

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

这是一份简单的快速入门指南。有关如何使用 Cloudflare OpenNext 适配器的详细文档，请访问 OpenNext 网站 ↗。

什么是 Next.js？

Next.js ↗ 是用于构建全栈应用的 React ↗ 框架。

Next.js 支持服务端和客户端渲染，以及 Partial Prerendering，让你在同一路由中组合静态和动态组件。

你可以使用 OpenNext 适配器将 Next.js 应用部署到 Cloudflare Workers。

Next.js 支持的功能

Cloudflare OpenNext 适配器支持大多数 Next.js 功能：

功能 Cloudflare 适配器 说明
App Router 🟢 支持
Pages Router 🟢 支持
Route Handlers 🟢 支持
React Server Components 🟢 支持
Static Site Generation (SSG) 🟢 支持
Server-Side Rendering (SSR) 🟢 支持
Incremental Static Regeneration (ISR) 🟢 支持
Server Actions 🟢 支持
Response streaming 🟢 支持
使用 next/after 的异步工作 🟢 支持
Middleware 🟢 支持
Image optimization 🟢 支持 通过 Cloudflare Images 支持
Partial Prerendering (PPR) 🟢 支持 PPR 在 Next.js 中为实验性功能
Composable Caching ('use cache') 🟢 支持 Composable Caching 在 Next.js 中为实验性功能
Middleware 中的 Node.js ⚪ 尚未支持 Next.js 15.2 引入的 Node.js middleware 尚未支持

在 Workers 上部署新的 Next.js 项目

  1. 使用 create-cloudflare CLI (C3) 创建新项目。

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

    幕后发生了什么？

    运行此命令时，C3 会创建新的项目目录，启动 Next.js 官方搭建工具 ↗，并 为 Cloudflare 配置项目。随后会提供立即将应用部署到 Cloudflare 的选项。

  2. 在本地开发。

    创建项目后，在项目目录中运行以下命令以启动本地开发服务器。 该命令使用 Next.js 开发服务器。每次更新源代码时快速重新加载应用，提供最佳开发体验。

    npm run dev

  3. 使用 Cloudflare 适配器测试和预览站点。

    npm run preview

    dev 和 preview 有什么区别？

    上一步使用的命令使用 Next.js 开发服务器， 它在 Node.js 中运行。然而，你部署的应用将在 Cloudflare Workers 上运行，使用 workerd 运行时。因此，在 运行集成测试和预览应用时，应使用 preview 命令，它更接近生产环境，因为使用 wrangler dev 在 workerd 运行时中执行 应用。

  4. 部署项目。

    你可以从本地机器或任何 CI/CD 系统（包括 Workers Builds）将项目部署到 *.workers.dev 子域或自定义域名。使用以下命令进行构建和部署。若使用 CI 服务，请相应更新你的「deploy command」。

    npm run deploy

在 Workers 上部署现有 Next.js 项目

Next.jsDetected
Generated configuration
wrangler.jsonc
main:.open-next/worker.js
wrangler.jsonc
assets:directory: .open-next/assets
wrangler.jsonc
compatibility_flags:nodejs_compat
wrangler.jsonc
observability:enabled: true
package.json
adapter:@opennextjs/cloudflare
WorkersDeployed
Wrangler handles configuration automatically

手动配置

若希望手动配置项目，请按以下步骤操作。

  1. 安装 @opennextjs/cloudflare ↗

    npm i @opennextjs/cloudflare@latest

  2. 将 wrangler CLI 安装为 devDependency

    npm i -D wrangler@latest

  3. 添加 Wrangler 配置文件

    在项目根目录创建 Wrangler 配置文件，内容如下：

    {
	"$schema": "./node_modules/wrangler/config-schema.json",
	"main": ".open-next/worker.js",
	"name": "my-app",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"assets": {
		"directory": ".open-next/assets",
		"binding": "ASSETS"
	}
}
    "$schema" = "./node_modules/wrangler/config-schema.json"
main = ".open-next/worker.js"
name = "my-app"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[assets]
directory = ".open-next/assets"
binding = "ASSETS"

  4. 添加 OpenNext 配置文件

    在项目根目录创建名为 open-next.config.ts 的 OpenNext 配置文件，内容如下：

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

export default defineCloudflareConfig();

  5. 更新 package.json

    你可以将以下脚本添加到 package.json：

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

    用法

    • preview：构建应用并在本地提供服务，通过单个命令 快速预览在 Workers 运行时中本地运行的应用。
    • deploy：构建应用，然后部署到 Cloudflare
    • cf-typegen：在项目根目录生成包含 env 类型的 cloudflare-env.d.ts 文件。

  6. 在本地开发。

    创建项目后，在项目目录中运行以下命令以启动本地开发服务器。 该命令使用 Next.js 开发服务器。每次更新源代码后快速重新加载应用，提供最佳开发体验。

    npm run dev

  7. 使用 Cloudflare 适配器测试站点。

    上一步使用的命令使用 Next.js 开发服务器以提供出色的开发体验。 然而你的应用将在 Cloudflare Workers 上运行，因此你需要运行集成测试并验证应用在此环境中正常工作。

    npm run preview

  8. 部署项目。

    你可以从本地机器或任何 CI/CD 系统（包括 Workers Builds）将项目部署到 *.workers.dev 子域或自定义域名。使用以下命令进行构建和部署。若使用 CI 服务，请相应更新你的「deploy command」。

    npm run deploy

这篇文档对您有帮助吗？