Get Started - OpenNext 中文文档

开始使用

新应用

要创建一个新的 Next.js 应用，并预配置为使用 @opennextjs/cloudflare 在 Cloudflare 上运行，请运行：

npm create cloudflare@latest -- my-next-app --framework=next --platform=workers

现有的 Next.js 应用

转换现有 Next.js 应用的最简单方法是使用 migrate 命令：

npx @opennextjs/cloudflare migrate

此命令自动化了下面的所有设置步骤。如果您的账户启用了 R2，它还会创建一个 R2 桶用于缓存。请参阅 CLI 文档了解更多详情。

或者，您可以遵循下面的手动步骤。

1. 安装 @opennextjs/cloudflare

首先，安装 @opennextjs/cloudflare (opens in a new tab)：

npm install @opennextjs/cloudflare@latest

2. 安装 Wrangler

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

npm install --save-dev wrangler@latest

💡

您必须使用 Wrangler 版本 3.99.0 或更高版本才能使用 @opennextjs/cloudflare 部署 Next.js 应用。

3. 创建 wrangler 配置文件

此步骤是可选的，因为 @opennextjs/cloudflare 会在构建过程中为您创建此文件（如果尚未存在）。

您的应用需要 wrangler 配置文件 (opens in a new tab) 才能进行预览和部署，这也是您配置 Worker 并通过绑定 (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": [
    // 启用 Node.js API
    // 参见 https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-compatibility-flag
    "nodejs_compat",
    // 允许获取您应用中的 URL
    // 参见 https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public
    "global_fetch_strictly_public",
  ],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS",
  },
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      // 服务应与您的 worker 的 "name" 匹配
      "service": "my-app",
    },
  ],
  "r2_buckets": [
    // 创建一个绑定名为 "NEXT_INC_CACHE_R2_BUCKET" 的 R2 绑定
    // {
    //   "binding": "NEXT_INC_CACHE_R2_BUCKET",
    //   "bucket_name": "<BUCKET_NAME>",
    // },
  ],
  "images": {
    // 启用图像优化
    // 参见 https://opennext.js.org/cloudflare/howtos/image
    "binding": "IMAGES",
  },
}

💡

如上所示：- 您必须启用 nodejs_compat 兼容性标志 (opens in a new tab) 并将您的兼容性日期 (opens in a new tab) 设置为 2024-09-23 或更高版本，以便您的 Next.js 应用能与 @opennextjs/cloudflare 一起工作 - main 和 assets 值也不应更改，除非您以某种方式修改了构建输出结果 - 您可以添加一个名为 NEXT_INC_CACHE_R2_BUCKET 的绑定以利用 Next.js 的缓存，如缓存文档中所述

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

此步骤是可选的，因为 @opennextjs/cloudflare 会在构建过程中为您创建此文件（如果尚未存在）。

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

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

💡

要使用如上所示的 OpenNextConfig 类型（这不是必须的），您需要将 @opennextjs/aws NPM 包安装为开发依赖。

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": "next build",
"preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
"deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
"upload": "opennextjs-cloudflare build && opennextjs-cloudflare upload",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts",

build 脚本必须调用 Next.js 构建命令，它将由 opennextjs-cloudflare build 调用。
npm run preview：构建您的应用并在本地提供服务，允许您通过单个命令快速预览在 Workers 运行时中本地运行的应用。
npm run deploy：构建您的应用，然后立即将其部署到 Cloudflare。
npm run upload：构建您的应用，然后将其新版本 (opens in a new tab) 上传到 Cloudflare。
cf-typegen：在项目根目录生成一个 cloudflare-env.d.ts 文件，其中包含 env 的类型 (opens in a new tab)。

7. 添加静态资源缓存

添加一个 public/_headers 文件，至少包含以下头信息：

/_next/static/*
  Cache-Control: public,max-age=31536000,immutable

请参阅静态资源缓存文档了解更多信息。

8. 使用 Cloudflare R2 添加缓存

请参阅缓存文档了解如何在 OpenNext 项目中启用 Next.js 缓存的信息。

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

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

edge 运行时尚未得到 @opennextjs/cloudflare 的支持。

10. 将 `.open-next` 添加到 `.gitignore`

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

11. 移除 `@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 规则

12. 本地开发

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

修改您的 Next.js 配置文件以导入并调用 initOpenNextCloudflareForDev 实用程序来自 @opennextjs/cloudflare 包。这确保了 Next.js 开发服务器能够最佳地集成 open-next cloudflare 适配器，并且对于在本地开发期间使用绑定是必要的。

这是一个调用该实用程序的 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 中。这允许您在与应用部署到 Cloudflare 时相同的运行时中测试更改。

13. 部署到 Cloudflare Workers

要么通过命令行部署：

npm run deploy

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

开始使用

新应用

现有的 Next.js 应用

1. 安装 @opennextjs/cloudflare

2. 安装 Wrangler

3. 创建 wrangler 配置文件

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

5. 添加 .dev.vars 文件

6. 更新 package.json 文件