开始使用

新应用

要创建一个新的 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 并通过 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",
  },
  "kv_namespaces": [
    // 创建一个绑定名为 "NEXT_CACHE_WORKERS_KV" 的 KV binding
    // 以启用基于 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 { defineCloudflareConfig } from "@opennextjs/cloudflare";
import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache";
 
export default defineCloudflareConfig({
  incrementalCache: kvIncrementalCache,
});

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 字段中：

"preview": "opennextjs-cloudflare && wrangler dev",
"deploy": "opennextjs-cloudflare && wrangler 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 添加缓存

请参阅 Caching docs 以获取有关在 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。

修改您的 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 bindings 的本地版本，如 bindings documentation 中所示。

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

12. 部署到 Cloudflare Workers

要么通过命令行部署：

npm run deploy

要么 连接 GitHub 或 GitLab 仓库 (opens in a new tab)，Cloudflare 将自动构建并部署您合并到生产分支的每个 pull request。