开始使用

新建应用

要创建一个新的 Next.js 应用（已预配置为使用 @opennextjs/cloudflare 在 Cloudflare 上运行），请执行：

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

现有 Next.js 应用

1. 安装 @opennextjs/cloudflare

首先安装 @opennextjs/cloudflare (opens in a new tab):

npm install --save-dev @opennextjs/cloudflare

2. 安装 Wrangler 并添加 wrangler.toml 文件

将 Wrangler CLI (opens in a new tab) 安装为开发依赖：

npm install -D wrangler@latest

然后在 Next.js 应用的根目录下添加 wrangler.toml (opens in a new tab) 文件：

main = ".worker-next/index.mjs"
name = "my-app"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
assets = { directory = ".worker-next/assets", binding = "ASSETS" }

wrangler.toml 是配置 Worker 和定义其可通过 绑定 (opens in a new tab) 访问哪些资源的地方。

3. 更新 package.json

在 package.json 文件的 scripts 字段中添加以下内容：

"build:worker": "cloudflare",
"dev:worker": "wrangler dev --port 8771",
"preview:worker": "npm run build:worker && npm run dev:worker",
"deploy:worker": "npm run build:worker && wrangler deploy"

• npm run build:worker: 运行 @opennextjs/cloudflare (opens in a new tab) 适配器。该命令会先在后台执行 next build 构建应用，然后将构建输出转换为可以通过 Wrangler (opens in a new tab) 本地运行并部署到 Cloudflare 的格式。
• npm run dev:worker: 获取 build:worker 生成的输出，并在 workerd (opens in a new tab)（开源的 Workers Runtime）中本地运行，使应用能在与生产环境相同的运行时环境中本地运行。如果改为运行 next dev，应用将在 Node.js 中运行，这与 Workers 运行时是不同的 JavaScript 环境，行为和 API 会有所差异。
• npm run preview:worker: 先运行 build:worker 再运行 dev:worker，通过单个命令快速预览应用在 Workers 运行时中的本地运行效果。
• npm run deploy: 构建应用并部署到 Cloudflare

4. 使用 Workers KV 添加缓存

关于如何在 OpenNext 项目中启用 Next.js 缓存，请参阅 缓存文档。

5. 移除 @cloudflare/next-on-pages（如适用）

如果您的 Next.js 应用当前使用 @cloudflare/next-on-pages，需要移除该依赖并做一些调整。

移除 export const runtime = "edge";

在部署应用前，请从 next.config.js 文件中移除 export const runtime = "edge"; 这行代码。使用 @opennextjs/cloudflare 时不需要这行配置。

将 .worker-next 添加到 .gitignore

你应该将 .worker-next 添加到 .gitignore 文件中，以防止构建输出被提交到代码仓库。

卸载 @cloudflare/next-on-pages

你应该卸载 @cloudflare/next-on-pages 并移除所有相关引用。

在 package.json 中：

"scripts": {
-    "pages:build": "npx @cloudflare/next-on-pages",
-    "preview": "npm run pages:build && wrangler pages dev",
-    "deploy": "npm run pages:build && wrangler pages deploy"
 
"devDependencies": {
-    "@cloudflare/next-on-pages": "*",

（记得同时从 .eslintrc.js 文件中移除 eslint-plugin-next-on-pages (opens in a new tab)）

你不再需要在 next.config.mjs 文件中调用 setupDevPlatform()：

并且你需要将 @cloudflare/next-on-pages 中的 getRequestContext 替换为 @opennextjs/cloudflare 中的 getCloudflareContext：

- import { getRequestContext } from "@cloudflare/next-on-pages";
+ import { getCloudflareContext } from "@opennextjs/cloudflare";

6. 本地开发

你可以在本地开发时继续运行 next dev。

在本地开发期间，你可以访问 Cloudflare 绑定的本地版本，如 绑定文档 中所述。

在步骤 3 中，我们还添加了 npm run preview:worker 命令，这允许你快速预览应用在 Workers 运行时中的本地运行情况，而不是在 Node.js 中。这使你能在与应用部署到 Cloudflare 时相同的运行时环境中测试更改。

7. 部署到 Cloudflare Workers

可以通过命令行部署：

npm run deploy:worker

或者连接 Github 或 Gitlab 仓库 (opens in a new tab)，Cloudflare 会自动构建并部署每个合并到生产分支的 pull request。