OpenNext 适配器

使用本指南维护现有 OpenNext 应用程序。在兼容性允许时迁移到 vinext。

OpenNext ↗ 会适配 next build 的输出，使其可以在包括 Cloudflare Workers 在内的不同平台上运行。

支持的功能

Cloudflare OpenNext 适配器支持大多数 Next.js 功能：

功能	Cloudflare OpenNext 适配器	说明
App Router	支持
Pages Router	支持
Route Handlers	支持
React Server Components	支持
Static Site Generation (SSG)	支持
Server-Side Rendering (SSR)	支持
Incremental Static Regeneration (ISR)	支持
Server Actions	支持
Response streaming	支持
使用 `next/after` 的异步工作	支持
Middleware	支持
图像优化	支持	通过 Cloudflare Images 支持。
Partial Prerendering (PPR)	支持	PPR 在 Next.js 中为实验性功能。
Composable Caching（`"use cache"`）	支持	Composable Caching 在 Next.js 中为实验性功能。
Middleware 中的 Node.js	尚不支持	Next.js 15.2 引入的 Node.js middleware 尚不支持。

有关详细的 OpenNext 文档，请参阅 OpenNext for Cloudflare ↗。

手动配置 OpenNext

Wrangler 自动配置对 Next.js 项目使用 vinext。要使用 OpenNext，请手动配置适配器。

安装 OpenNext Cloudflare 适配器。
npm i @opennextjs/cloudflare@latest
yarn add @opennextjs/cloudflare@latest
pnpm add @opennextjs/cloudflare@latest
bun add @opennextjs/cloudflare@latest
安装 Wrangler。
npm i -D wrangler@latest
yarn add -D wrangler@latest
pnpm add -D wrangler@latest
bun add -d wrangler@latest

添加 Wrangler 配置文件。

在项目根目录创建包含以下内容的 Wrangler 配置文件：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-app",
  "main": ".open-next/worker.js",
  "upload_source_maps": true,
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  },
  "observability": {
    "enabled": true
  }
}

name = "my-app"
main = ".open-next/worker.js"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-14"
compatibility_flags = ["nodejs_compat"]

[assets]
directory = ".open-next/assets"
binding = "ASSETS"

[observability]
enabled = true

添加 OpenNext 配置文件。

在项目根目录创建 open-next.config.ts：
```
import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig();
```
使用此文件配置缓存等 OpenNext 功能。更多信息请参阅 OpenNext caching ↗。
更新 package.json。

添加用于预览、部署和生成 Cloudflare 类型的脚本：
```
{
  "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"
  }
}
```
脚本用法
- preview：构建应用并在 Workers 运行时中本地提供服务。
- deploy：构建应用并将其部署到 Cloudflare Workers。
- cf-typegen：生成包含 Cloudflare 绑定类型的 cloudflare-env.d.ts。
本地开发。

启动 Next.js 开发服务器。
npm run dev
yarn run dev
pnpm run dev
使用 OpenNext 预览。

在 Workers 运行时中预览应用程序。
npm run preview
yarn run preview
pnpm run preview
部署项目。

将项目部署到 Cloudflare Workers。
npm run deploy
yarn run deploy
pnpm run deploy