快速开始

新建应用

要创建一个预配置为使用 @opennextjs/cloudflare 在 Cloudflare 上运行的 Next.js 应用，执行以下命令：

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) 作为开发依赖安装:

npm install --save-dev wrangler@latest

3. 创建 wrangler 配置文件

你的应用需要一个 wrangler 配置文件 (opens in a new tab)来进行预览和部署，这也是你配置 Worker 并定义它可以通过 bindings (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 文件

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

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",
      // 设置为 "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 文件

接着，在 Next.js 应用的根目录下添加 .dev.vars (opens in a new tab) 文件：

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 Runtime）中本地运行，让你可以在与生产环境相同的运行时中本地运行应用。如果改为运行 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 规则

11. 本地开发

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

在本地开发期间，你可以访问 Cloudflare bindings 的本地版本，具体参考 bindings 文档。

在第 3 步中，我们还添加了 npm run preview:worker 命令，这能让你快速预览应用在 Workers runtime 而非 Node.js 中的运行情况，方便你在与生产环境相同的运行时中测试变更。

12. 部署到 Cloudflare Workers

可以通过命令行部署：

npm run deploy:worker

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