用途
Cloudflare OpenNext 用于把 Next.js 应用部署到 Cloudflare Workers。它基于 @opennextjs/cloudflare 适配器，支持 App Router、Pages Router、ISR、SSG 以及 Cloudflare 绑定。适合以下场景：为 Cloudflare Workers 创建新的 Next.js 应用；把现有 Next.js 应用迁移到 Cloudflare；使用 R2、KV 或 D1 配置 ISR/SSG 缓存；访问 Cloudflare 绑定（KV、R2、D1、Durable Objects、AI）；在 Next.js 中使用数据库和 ORM（Drizzle、Prisma）；排查部署问题或包体积问题。
主要能力
适配器的工作流程是：运行 next build 生成 Next.js 构建输出；把构建输出转换为可在 Cloudflare Workers 运行时运行的形式；输出到 .open-next/ 目录，入口为 worker.js；静态文件（_next/static、public）使用 Workers Static Assets。
它使用 Next.js 的 Node.js 运行时，而不是 Edge 运行时。Node.js 运行时通过 nodejs_compat 标志提供完整的 Node.js API 兼容性，支持比 Edge 运行时更多的 Next.js 特性，并可访问全部 Cloudflare 绑定。
支持的特性包括：App Router（完整）、Pages Router（完整，含 API 路由）、Route Handlers（完整）、动态路由（完整，如 [slug]、[...slug]）、SSG、SSR、ISR、PPR、中间件（部分，标准中间件可用，Next.js 15.2+ 的 Node Middleware 不支持）、图片优化（通过 Cloudflare Images 绑定）、可组合缓存（'use cache' 指令）、next/font、after() 后台任务。Turbopack 不支持，需使用标准构建。支持的 Next.js 版本：Next.js 15 的全部次要和补丁版本；Next.js 14 仅最新次要版本。
使用方式
新建应用：
npm create cloudflare@latest -- my-next-app --framework=next --platform=workers
cd my-next-app
npm run dev # Local development with Next.js
npm run preview # Preview in Workers runtime
npm run deploy # Deploy to Cloudflare
迁移现有应用：安装依赖（npm install @opennextjs/cloudflare@latest；npm install --save-dev wrangler@latest），创建 wrangler.jsonc，创建 open-next.config.ts，更新 next.config.ts，在 package.json 中添加脚本，然后部署。
wrangler.jsonc 的必需设置包括：nodejs_compat 兼容标志；compatibility_date 不早于 2024-09-23；WORKER_SELF_REFERENCE 服务绑定（必须与 worker 名称一致）；main 和 assets 路径不应更改。
open-next.config.ts 用于配置缓存和 OpenNext 行为，例如使用 r2IncrementalCache。该文件若不存在会自动生成。
next.config.ts 中通过 initOpenNextCloudflareForDev() 在 next dev 期间启用绑定访问。
.dev.vars 用于本地开发环境变量，NEXTJS_ENV 变量决定加载哪个 Next.js .env 文件：development 对应 .env.development，production 对应 .env.production（默认）。
使用 getCloudflareContext() 可在任意路由中访问绑定，例如在 Route Handler、API Route、Server Component 中读取 KV、R2、D1、Durable Objects，获取请求信息（如 cf?.country），以及用 ctx.waitUntil() 执行后台任务。对于 SSG 路由，需使用异步模式：await getCloudflareContext({ async: true })。注意：SSG 期间，.dev.vars 中的密钥和本地绑定值会被包含进静态构建，需谨慎处理敏感数据。
TypeScript 类型可通过 npx wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts 生成，绑定变更后需重新运行。
CLI 命令由 opennextjs-cloudflare 封装 Wrangler：build 构建并转换；preview 本地预览；deploy 部署；upload 上传为版本（不部署）；populateCache local/remote 填充缓存（preview/deploy/upload 会自动调用）。推荐的 package.json 脚本包括 dev、build、preview、deploy、upload、cf-typegen。
缓存与图片
缓存类型包括：Incremental Cache（ISR/SSG 页面数据，存储可选 R2、KV、Static Assets）；Queue（基于时间的重新验证，存储可选 Durable Objects、Memory）；Tag Cache（按需重新验证，存储可选 D1、Durable Objects）。
图片优化通过 Cloudflare Images 绑定启用，Next.js 的 <Image> 组件会自动使用 Cloudflare Images，会产生额外费用。兼容性说明：支持 PNG、JPEG、WEBP、AVIF、GIF、SVG；不支持 minimumCacheTTL；不支持 dangerouslyAllowLocalIP。
数据库与 ORM
关键规则：不要在 Workers 中创建全局数据库客户端，应按请求创建。错误做法是全局创建 Pool；正确做法是使用 React 的 cache() 创建请求作用域实例，并设置 maxUses: 1 避免跨请求复用连接。
适用场景与限制
适用场景包括：新建面向 Workers 的 Next.js 项目、从 next-on-pages 迁移、配置 ISR/SSG 缓存、在 Next.js 中使用数据库与 ORM、排查部署与包体积问题。
限制与注意事项：不要使用 Edge 运行时（移除 export const runtime = "edge"）；不要使用 Turbopack；不要创建全局数据库客户端；Worker 体积不要超过 10 MiB（免费计划为 3 MiB）；不要使用 next-on-pages（应使用 @opennextjs/cloudflare）；不要提交 .open-next/ 目录；不支持 Node Middleware。
从 @cloudflare/next-on-pages 迁移时：卸载 @cloudflare/next-on-pages 和 eslint-plugin-next-on-pages；安装 @opennextjs/cloudflare；更新 next.config.ts（移除 setupDevPlatform()，替换为 initOpenNextCloudflareForDev()）；更新导入（用 @opennextjs/cloudflare 的 getCloudflareContext 替换 @cloudflare/next-on-pages 的 getRequestContext）；移除 Edge 运行时导出；更新 wrangler.jsonc；移除 next-on-pages 的 eslint 规则。
开发工作流与最佳实践
开发工作流：npm run dev 使用 Next.js 开发服务器；npm run preview 在 Workers 运行时预览（比部署更快）；npm run deploy 部署到生产；npm run cf-typegen 在绑定变更后更新 TypeScript 类型。next dev 使用 Node.js 运行时，绑定通过 initOpenNextCloudflareForDev() 可用；npm run preview 使用 Wrangler 的 Workers 运行时，更接近生产环境；两者都支持热重载。
最佳实践：从简单开始（仅 SSG 站点使用 Static Assets 缓存）；逐步添加缓存（需要 ISR 时启用 R2 缓存）；监控包体积（保持在 10 MiB 压缩以内，可使用 ESBuild Bundle Analyzer）；使用 TypeScript（运行 cf-typegen 获取绑定类型）；部署前用 npm run preview 测试；缓存数据库客户端（使用 React 的 cache() 创建请求作用域实例）；启用可观测性（在 wrangler.jsonc 中添加 observability 以便日志记录）；构建时使用远程绑定（为 ISR 启用真实数据）。
官方示例位于 @opennextjs/cloudflare 仓库，包括 create-next-app（基础 Next.js 起步模板）、middleware（中间件用法）、vercel-blog-starter（SSG 博客示例）。