使用 vinext 创建或迁移 Next.js 应用,并将其部署到 Cloudflare Workers。
Cloudflare 建议将 vinext ↗ 作为在 Cloudflare Workers 上运行 Next.js 应用的默认方式。vinext 提供两种起点:使用 create-vinext-app 搭建新的 Workers 就绪应用,或通过一次非破坏性的 vinext init 将 vinext 添加到现有 Next.js 16 应用(现有的 next dev 继续可用)。无论哪种方式,你都不需要 Cloudflare 专用模板。
已经在使用 OpenNext?请参阅其他 Next.js 部署路径。
Next.js ↗ 是用于构建全栈应用的 React ↗ 框架。
Next.js 支持服务器端渲染、客户端渲染、静态生成、React Server Components、Server Actions、路由处理程序和 middleware。
vinext ↗ 是一个重新实现 Next.js API 表面的 Vite 插件。你可以保留现有的 app/、pages/、next.config.js 和 public/ 目录,同时使用 Vite 工具链。
vinext 目前处于 Beta。在将它用于现有生产应用之前,请从项目目录运行兼容性检查,并查看 vinext 兼容性仪表板 ↗。
npx vinext checkyarn dlx vinext checkpnpx vinext checkvinext 在 Cloudflare Workers 上支持大多数常用 Next.js 功能:
| 功能 | vinext 支持 | 说明 |
|---|---|---|
| App Router | 支持 | 包括 layouts、路由处理程序、metadata、loading、error 和 not-found 路由。 |
| Pages Router | 支持 | 包括 getStaticProps、getStaticPaths 和 getServerSideProps。 |
| React Server Components | 支持 | 使用 Vite 的 React Server Components 支持。 |
| Server Actions | 支持 | 可与表单和服务器变更一起使用。 |
| 服务器端渲染 | 支持 | 包括流式渲染。 |
| 静态生成和静态导出 | 支持 | 静态导出使用 output: "export"。 |
| Incremental Static Regeneration (ISR) | 支持 | 使用 stale-while-revalidate 缓存模型,以便 Worker 可以提供缓存内容同时在后台刷新。请参阅异步重新验证。 |
| Middleware 和 proxy 路由 | 支持 | 包括 middleware.ts 和 proxy.ts。 |
next/* 导入 |
大部分支持 | 查看兼容性仪表板了解模块级详情。 |
| Cloudflare 绑定(binding) | 支持 | 在 server components、路由处理程序和 server actions 中使用 cloudflare:workers。 |
| 图像优化 | 部分支持 | Cloudflare 图像优化在请求时可用。 |
有关详细兼容性结果,请参阅 vinext compatibility ↗。
大多数 Next.js 项目可以从同一工作流开始:打开 Next.js 应用、检查兼容性、添加 vinext,然后部署到 Workers。
- 如果希望代理检查项目并应用迁移,请使用通过代理添加 vinext。
- 如果希望直接、可重复的命令行设置,请使用通过 CLI 添加 vinext。
- 如果希望搭建已为 Workers 配置好的新项目,请使用创建 Cloudflare 就绪项目。
当你希望编码代理检查 Next.js 项目、运行兼容性检查、更新配置并启动 vinext 开发服务器时,使用 vinext Agent Skill。
-
打开你的 Next.js 项目。
使用现有项目,或通过你偏好的 Next.js 设置流程创建项目。
-
安装 vinext Agent Skill。
npx skills add cloudflare/vinextyarn dlx skills add cloudflare/vinextpnpx skills add cloudflare/vinext -
向代理发出提示。
在编码代理中运行以下提示:
migrate this project to vinext该 skill 会运行 vinext 兼容性检查、应用迁移,并标记需要手动处理的问题。
-
使用 vinext 开发。
启动 vinext 开发服务器。
npm run dev:vinextyarn run dev:vinextpnpm run dev:vinext -
使用 vinext 构建。
使用 vinext 构建生产输出。
npm run build:vinextyarn run build:vinextpnpm run build:vinext -
部署到 Workers。
使用 vinext Cloudflare 部署命令进行部署。
npx @vinext/cloudflare deployyarn dlx @vinext/cloudflare deploypnpx @vinext/cloudflare deploy
当你希望直接进行命令行设置时,使用 vinext init。迁移是非破坏性的:在测试 Cloudflare Workers 部署期间,现有 Next.js 设置会继续与 vinext 一起工作。
-
打开你的 Next.js 项目。
使用现有项目,或通过你偏好的 Next.js 设置流程创建项目。
-
检查兼容性。
从 Next.js 项目目录运行 vinext 兼容性检查。
npx vinext checkyarn dlx vinext checkpnpx vinext check在继续之前审查报告的兼容性问题。
-
初始化 vinext。
运行 vinext initializer,并在提示时选择 Cloudflare Workers 作为部署目标。
npx vinext inityarn dlx vinext initpnpx vinext initvinext init会安装 vinext 和 Vite 依赖、添加 vinext 脚本、生成 Vite 配置,并创建 Cloudflare Workers 配置。 -
使用 vinext 开发。
启动 vinext 开发服务器。
npm run dev:vinextyarn run dev:vinextpnpm run dev:vinext -
使用 vinext 构建。
使用 vinext 构建生产输出。
npm run build:vinextyarn run build:vinextpnpm run build:vinext -
部署到 Workers。
使用 vinext Cloudflare 部署命令进行部署。
npx @vinext/cloudflare deployyarn dlx @vinext/cloudflare deploypnpx @vinext/cloudflare deploy
当你希望搭建已为 Cloudflare Workers 配置好的新 Next.js 项目时,使用 create-cloudflare CLI(C3)。
-
使用 C3 创建新项目。
npm create cloudflare@latest -- my-next-app --framework=nextyarn create cloudflare my-next-app --framework=nextpnpm create cloudflare@latest my-next-app --framework=next命令行为
C3 会创建新的 Next.js 项目,为 Cloudflare Workers 配置 vinext,安装所需依赖,并提供部署 应用的选项。
-
使用 vinext 开发。
切换到项目目录并启动本地开发服务器。
npm run devyarn run devpnpm run dev -
构建应用。
在部署或测试生产构建之前运行生成的构建脚本。
npm run buildyarn run buildpnpm run build -
部署项目。
将项目部署到
*.workers.dev子域名 或自定义域名。npm run deployyarn run deploypnpm run deploy
在部署到 Workers 的 vinext 应用中,使用 cloudflare:workers 从 server components、路由处理程序和 server actions 访问绑定。在 Wrangler 配置中定义绑定,然后使用 wrangler types 生成类型。
例如,你可以在服务器端应用代码中从 cloudflare:workers 导入 env,以访问 D1、R2、KV、Durable Objects、Workers AI、Queues、Vectorize 及其他绑定。
vinext 是 Cloudflare Workers 上 Next.js 应用的推荐路径,但其他部署路径仍有文档:
| 路径 | 适用场景 |
|---|---|
| OpenNext 适配器 | 你维护现有 OpenNext 应用,因兼容性缺口尚无法迁移到 vinext。 |
| Pages 上的静态 Next.js | 你的应用是静态导出,并且你明确希望将其部署到 Cloudflare Pages。 |