开始使用

新应用

要创建一个新的 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) 安装为 devDependency：

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 运行时）中本地运行它，允许你在与生产环境相同的环境中本地运行应用。如果你改为运行 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 将自动构建并部署你合并到生产分支的每个拉取请求。