开始使用

新应用

要创建一个新的 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@latest

2. 安装 Wrangler

将 Wrangler CLI (opens in a new tab) 作为 devDependency 安装：

npm install --save-dev wrangler@latest

3. 创建 wrangler 配置文件

您的应用需要 wrangler 配置文件 (opens in a new tab) 才能进行预览和部署，这也是您配置 Worker 并通过 绑定 (opens in a new tab) 定义它可以访问哪些资源的地方。

您可以在 Next.js 应用的根目录下自行创建一个名为 wrangler.json 的文件，内容如下：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "main": ".open-next/worker.js",
  "name": "my-app",
  "compatibility_date": "2024-12-30",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS",
  },
  "kv_namespaces": [
    // 创建一个绑定名为 "NEXT_CACHE_WORKERS_KV" 的 KV 绑定
    // 以启用基于 KV 的缓存：
    // {
    //   "binding": "NEXT_CACHE_WORKERS_KV",
    //   "id": "<BINDING_ID>"
    // }
  ],
}

4. 添加 open-next.config.ts 文件

将 open-next.config.ts (opens in a new tab) 文件添加到 Next.js 应用的根目录：

import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
import cache from "@opennextjs/cloudflare/kvCache";
 
const config: OpenNextConfig = {
  default: {
    override: {
      wrapper: "cloudflare-node",
      converter: "edge",
      // 将 `incrementalCache` 设置为 "dummy" 以禁用 KV 缓存
      incrementalCache: async () => cache,
      tagCache: "dummy",
      queue: "dummy",
    },
  },
 
  middleware: {
    external: true,
    override: {
      wrapper: "cloudflare-edge",
      converter: "edge",
      proxyExternalRequest: "fetch",
    },
  },
};
 
export default config;

5. 添加 .dev.vars 文件

然后，将 .dev.vars (opens in a new tab) 文件添加到 Next.js 应用的根目录：

NEXTJS_ENV=development

NEXTJS_ENV 变量定义了加载 Next.js .env 文件时要使用的环境。未定义时默认为 "production"。

6. 更新 package.json 文件

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

"build:worker": "opennextjs-cloudflare",
"dev:worker": "wrangler dev --port 8771",
"preview": "npm run build:worker && npm run dev:worker",
"deploy": "npm run build:worker && wrangler deploy",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts",

• npm run build:worker：运行 @opennextjs/cloudflare (opens in a new tab) 适配器。这首先会通过运行 package.json 中的 build 脚本来构建您的应用（Next.js 应用默认使用 next build），然后将构建输出转换为您可以使用 Wrangler (opens in a new tab) 在本地运行并部署到 Cloudflare 的格式。OpenNext 使用的构建命令可以通过 OpenNext 配置中的 buildCommand 选项进行覆盖。
• npm run dev:worker：获取 build:worker 生成的输出，并在 workerd (opens in a new tab)（开源 Workers 运行时）中本地运行它，允许您在与生产环境相同的环境中本地运行应用。如果您改为运行 next dev，您的应用将在 Node.js 中运行，这是与 Workers 运行时不同的 JavaScript 运行时，行为和 API 存在差异。
• npm run preview：运行 build:worker 然后 dev:worker，允许您通过单个命令快速预览在 Workers 运行时中本地运行的应用。
• npm run deploy：构建您的应用，然后将其部署到 Cloudflare
• cf-typegen：在项目根目录生成一个 cloudflare-env.d.ts 文件，其中包含 env 的类型 (opens in a new tab)。

7. 使用 Workers KV 添加缓存

请参阅 缓存文档 以获取在 OpenNext 项目中启用 Next.js 缓存的信息。

8. 如果存在，移除任何 export const runtime = "edge";

在部署应用之前，从任何源文件中移除 export const runtime = "edge"; 行。

@opennextjs/cloudflare 尚不支持 edge runtime。

9. 将 .open-next 添加到 .gitignore

您应该将 .open-next 添加到 .gitignore 文件中，以防止构建输出被提交到您的仓库。

10. 移除 @cloudflare/next-on-pages（如有必要）

如果您的 Next.js 应用当前使用 @cloudflare/next-on-pages，您需要移除它，并进行一些更改。

卸载 @cloudflare/next-on-pages (opens in a new tab) 包以及 eslint-plugin-next-on-pages (opens in a new tab) 包（如果存在）。

从您的源代码和配置文件中移除这些包的任何引用。 这包括：

• Next.js 配置文件中的 setupDevPlatform() 调用
• 源文件中来自 @cloudflare/next-on-pages 的 getRequestContext 导入 （这些可以替换为来自 @opennextjs/cloudflare 的 getCloudflareContext 调用）
• Eslint 配置文件中设置的 next-on-pages eslint 规则

11. 本地开发

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

在本地开发期间，您可以访问 绑定文档 中指示的 Cloudflare 绑定的本地版本。

在第 3 步中，我们还添加了 npm run preview:worker，它允许您快速预览在 Workers 运行时中本地运行的应用，而不是在 Node.js 中。这允许您在与应用部署到 Cloudflare 时运行的相同的运行时中测试更改。

12. 部署到 Cloudflare Workers

要么通过命令行部署：

npm run deploy:worker

或者 连接 GitHub 或 GitLab 仓库 (opens in a new tab)，Cloudflare 将自动构建并部署您合并到生产分支的每个拉取请求。