快速开始

新建应用

要创建一个新的 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) 作为开发依赖安装：

npm install --save-dev wrangler@latest

3. 创建 wrangler 配置文件

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

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

{
  "$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",
  },
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      // 服务名称应与你的 worker 的 "name" 匹配
      "service": "my-app",
    },
  ],
  "kv_namespaces": [
    // 创建一个绑定名为 "NEXT_INC_CACHE_KV" 的 KV 绑定
    // 以启用基于 KV 的缓存：
    // {
    //   "binding": "NEXT_INC_CACHE_KV",
    //   "id": "<BINDING_ID>"
    // }
  ],
}

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

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

import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache";
 
export default defineCloudflareConfig({
  incrementalCache: kvIncrementalCache,
});

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 字段中添加以下内容：

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

• npm run preview: 构建应用并在本地运行，通过单一命令快速预览应用在 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。

修改您的 Next.js 配置文件，从 @opennextjs/cloudflare 包中导入并调用 initOpenNextCloudflareForDev 工具函数。这能确保 Next.js 开发服务器与 open-next cloudflare 适配器实现最佳集成，也是在本地开发中使用绑定(bindings)的必要条件。

以下是一个调用该工具的 Next.js 配置文件示例：

// next.config.ts
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  /* 在此处添加配置选项 */
};
 
export default nextConfig;
 
import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
initOpenNextCloudflareForDev();

在 Next.js 配置文件中添加 initOpenNextCloudflareForDev() 调用后，您就能在本地开发期间，在任何服务器代码中访问 绑定文档 中提到的 Cloudflare 绑定的本地版本。

在第 3 步中，我们还添加了 npm run preview 命令，这能让您快速预览应用在 Workers 运行时（而非 Node.js）中本地运行的效果。这样您就能在与生产环境相同的运行时中测试变更。

12. 部署到 Cloudflare Workers

您可以通过命令行部署：

npm run deploy

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