跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Next.js

最后更新 查看 MarkdownAgent 设置

使用 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?

Next.js ↗ 是用于构建全栈应用的 React ↗ 框架。

Next.js 支持服务器端渲染、客户端渲染、静态生成、React Server Components、Server Actions、路由处理程序和 middleware。

什么是 vinext?

vinext ↗ 是一个重新实现 Next.js API 表面的 Vite 插件。你可以保留现有的 app/、pages/、next.config.js 和 public/ 目录,同时使用 Vite 工具链。

vinext 目前处于 Beta。在将它用于现有生产应用之前,请从项目目录运行兼容性检查,并查看 vinext 兼容性仪表板 ↗。

npx vinext check

支持的功能

vinext 在 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

当你希望编码代理检查 Next.js 项目、运行兼容性检查、更新配置并启动 vinext 开发服务器时,使用 vinext Agent Skill。

  1. 打开你的 Next.js 项目。

    使用现有项目,或通过你偏好的 Next.js 设置流程创建项目。

  2. 安装 vinext Agent Skill。

    npx skills add cloudflare/vinext
  3. 向代理发出提示。

    在编码代理中运行以下提示:

    migrate this project to vinext

    该 skill 会运行 vinext 兼容性检查、应用迁移,并标记需要手动处理的问题。

  4. 使用 vinext 开发。

    启动 vinext 开发服务器。

    npm run dev:vinext
  5. 使用 vinext 构建。

    使用 vinext 构建生产输出。

    npm run build:vinext
  6. 部署到 Workers。

    使用 vinext Cloudflare 部署命令进行部署。

    npx @vinext/cloudflare deploy

通过 CLI 添加 vinext

当你希望直接进行命令行设置时,使用 vinext init。迁移是非破坏性的:在测试 Cloudflare Workers 部署期间,现有 Next.js 设置会继续与 vinext 一起工作。

  1. 打开你的 Next.js 项目。

    使用现有项目,或通过你偏好的 Next.js 设置流程创建项目。

  2. 检查兼容性。

    从 Next.js 项目目录运行 vinext 兼容性检查。

    npx vinext check

    在继续之前审查报告的兼容性问题。

  3. 初始化 vinext。

    运行 vinext initializer,并在提示时选择 Cloudflare Workers 作为部署目标。

    npx vinext init

    vinext init 会安装 vinext 和 Vite 依赖、添加 vinext 脚本、生成 Vite 配置,并创建 Cloudflare Workers 配置。

  4. 使用 vinext 开发。

    启动 vinext 开发服务器。

    npm run dev:vinext
  5. 使用 vinext 构建。

    使用 vinext 构建生产输出。

    npm run build:vinext
  6. 部署到 Workers。

    使用 vinext Cloudflare 部署命令进行部署。

    npx @vinext/cloudflare deploy

创建 Cloudflare 就绪项目

当你希望搭建已为 Cloudflare Workers 配置好的新 Next.js 项目时,使用 create-cloudflare CLI(C3)。

  1. 使用 C3 创建新项目。

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

    命令行为

    C3 会创建新的 Next.js 项目,为 Cloudflare Workers 配置 vinext,安装所需依赖,并提供部署 应用的选项。

  2. 使用 vinext 开发。

    切换到项目目录并启动本地开发服务器。

    npm run dev
  3. 构建应用。

    在部署或测试生产构建之前运行生成的构建脚本。

    npm run build
  4. 部署项目。

    将项目部署到 *.workers.dev 子域名 或自定义域名。

    npm run deploy

访问 Cloudflare 绑定(binding)

在部署到 Workers 的 vinext 应用中,使用 cloudflare:workers 从 server components、路由处理程序和 server actions 访问绑定。在 Wrangler 配置中定义绑定,然后使用 wrangler types 生成类型。

例如,你可以在服务器端应用代码中从 cloudflare:workers 导入 env,以访问 D1、R2、KV、Durable Objects、Workers AI、Queues、Vectorize 及其他绑定。

使用其他 Next.js 部署路径

vinext 是 Cloudflare Workers 上 Next.js 应用的推荐路径,但其他部署路径仍有文档:

路径 适用场景
OpenNext 适配器 你维护现有 OpenNext 应用,因兼容性缺口尚无法迁移到 vinext。
Pages 上的静态 Next.js 你的应用是静态导出,并且你明确希望将其部署到 Cloudflare Pages。

这篇文档对您有帮助吗?