Cloudflare
入门

快速开始

新建应用

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

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

现有 Next.js 应用

1. 安装 @opennextjs/cloudflare

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

npm install @opennextjs/cloudflare@latest
2. 安装 Wrangler

将 Wrangler CLI (opens in a new tab) 安装为开发依赖项：

npm install --save-dev wrangler@latest
💡

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

3. 创建 wrangler 配置文件

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

你的应用需要一个 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": [
    // 启用 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>",
    // },
  ],
}
💡

如上所示：- 你必须启用 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 会在构建过程中自动创建此文件（如果不存在）。

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

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 文件

接着，在 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": "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"; 这一行。

@opennextjs/cloudflare 目前尚不支持 edge 运行时。

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 规则
12. 本地开发

在本地开发时，你可以继续运行 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）中本地运行的效果。这样你就可以在与生产环境相同的运行时中测试变更。

13. 部署到 Cloudflare Workers

可以通过命令行部署：

npm run deploy

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