Next.js
Next.js是一个用于创建网站和应用程序的开源 React 框架。在本指南中，你将创建一个新的 Next.js 应用程序，并使用 Cloudflare Pages 进行部署。
本指南将指导你如何通过
next-on-pages 适配器部署使用
Edge Runtime 的全栈 Next.js 项目。
使用 create-cloudflare CLI(C3)创建新项目
create-cloudflare CLI (C3)](/pages/get-started/c3/) 将为 Cloudflare 页面配置 Next.js 网站。在终端中运行以下命令创建新的 Next.js 网站：
C3 会询问一系列设置问题。C3 还将安装必要的依赖项，包括 Wrangler CLI 和 @cloudflare/next-on-pages 适配器。
创建项目后，C3 将使用默认 Next.js 模板生成一个新的 my-next-app 目录，该模板已更新为与 Cloudflare Pages 完全兼容。
创建新项目时，C3 会让你选择通过 Direct Upload部署应用程序的初始版本。你可以在项目目录下运行以下命令，随时重新部署应用程序：
配置和部署不带 C3 的项目
如果你已经有一个 Next.js 项目，或希望不使用 C3 而手动创建和部署一个项目，Cloudflare 建议你使用 @cloudflare/next-on-pages，并参考其
README，以获取帮助你开发和部署项目的说明和其他信息。
Git 整合
除了直接上传部署外，你还可以通过Git 集成部署项目。Git 集成允许你将 GitHub 或 GitLab 仓库连接到 Pages 应用程序，并在每次推送新提交后自动构建和部署 Pages 应用程序。
设置需要对 Git 有基本了解。如果你是 Git 新手，请参考 GitHub 的 Git 手册汇总，了解如何在本地机器上设置 Git。
创建一个新的 GitHub 仓库
访问 repo.new，创建一个新的 GitHub 仓库。创建新仓库后，进入新创建的项目目录，准备并在终端运行以下命令将本地应用程序推送到 GitHub： 通过 Cloudflare 面板将你的应用程序连接到 GitHub 仓库
- 登录 Cloudflare 仪表板 并选择你的账户。
- 在账户主页，选择 工作者和页面> 创建应用程序> 页面> 连接到 Git。
如果你尚未授权访问你的 GitHub 帐户，系统将要求你进行授权。Cloudflare 需要这样才能从源代码监控和部署你的项目。如果你愿意，可以缩小对特定存储库的访问范围。不过，当你想在 Cloudflare 页面添加更多版本库时，你必须手动更新此列表 在你的 GitHub 设置中。
- 选择创建的新 GitHub 仓库，并在
**设置构建和部署**部分提供以下信息：
| Configuration option | Value |
|---|---|
| Production branch | main |
| Build command | npx @cloudflare/next-on-pages@1 |
| Build directory | .vercel/output/static |
你可以选择自定义项目名称字段。它默认为 GitHub 仓库的名称，但不必与之匹配。项目名称**值将被指定为*.pages.dev子域。
- 完成配置后，选择保存并部署。
你可以查看正在进行的首次部署管道。Pages 会按照指定安装所有依赖项并构建项目。Cloudflare Pages 会自动重建项目，并在每次推送新提交时进行部署。
此外，你还可以访问 预览部署，它可以重复拉取请求的构建和部署过程。有了它们，你就可以在将更改部署到生产环境之前，用一个真实的 URL 来预览对项目所做的更改。
在 Next.js 应用程序中使用绑定
绑定(binding) 允许你的应用程序与 Cloudflare 开发人员产品交互，如 KV、Durable Objects、R2 和 D1。
如果打算在项目中使用绑定，必须首先为本地和远程开发设置绑定。
为本地开发设置绑定
要设置用于本地开发的绑定，你需要使用
@cloudflare/next-on-pages/next-dev 提供的 setupDevPlatform 函数。setupDevPlatform 根据项目的 wrangler.toml文件设置平台模拟，以便 Next.js 应用程序在本地使用。
例如，要在本地使用 KV 绑定，请打开 Next.js 配置文件并添加
确保在项目根目录下有一个 wrangler.toml 文件，其中包含名为 MY_KV 的 KV 绑定声明：
为已部署的应用程序设置绑定
要访问已部署应用程序中的绑定，你需要 配置 任何必要的绑定，并通过 Cloudflare 面板中的项目设置页面将它们连接到你的项目。
为 Typescript 项目添加绑定
如果你的项目使用的是 TypeScript，你需要设置适当的类型支持，以便以类型安全和方便的方式访问绑定。
要获得适当的类型支持，你需要在项目中创建一个新的 env.d.ts 文件，并使用你的 bindings 扩展 CloudflareEnv(由 getRequestContext使用)接口。
下面是一个如何添加 KVNamespace 绑定的示例：
应用程序中的访问绑定
可使用 @cloudflare/next-on-pages 公开的 [getRequestContext]函数(
https://github.com/cloudflare/next-on-pages/blob/3846730c4a0d12/packages/next-on-pages/README.md#cloudflare-platform-integration)访问本地和远程绑定。下面的代码示例展示了如何在 App Router 应用程序的 hello API 路由中访问它们。
Image组件
Cloudflare 网络不提供与 Vercel 网络相同的图像优化支持。因此，Next.js 的 <Image /> 组件与在 Vercel 网络中的行为不同。
-
如果将应用程序作为静态网站构建，
<Image />组件将不提供任何图像。 -
如果使用
@cloudflare/next-on-pages构建应用程序，该组件将正常工作，但不会执行任何图像优化(无论你向其传递的 props是什么)。
这两种情况都可以通过为<image />组件设置适当的
loaders来改善，你可以使用任何你想要的图像优化服务。要使用 Cloudflare Images，请参阅 resize with Cloudflare Workers。
建议的开发工作流程
在开发 next-on-pages 应用程序时，这是 Cloudflare 推荐的开发工作流程：
使用标准 Next.js 开发服务器进行开发
Next.js提供的
标准开发服务器是获得快速、完美开发体验的最佳选择。next-dev 子模块(如本地绑定部分所述)使你可以使用 Next.js 的标准开发服务器，同时仍可访问你的 Cloudflare 绑定。
在本地构建并预览应用程序
为确保你的应用程序以完全兼容 Cloudflare Pages 的方式构建，在部署之前，或在开发过程中检查应用程序的正确性时，你需要使用 Cloudflare 的 workerd JavaScript 运行时在本地构建和预览应用程序。
如果你使用 C3 创建了项目，请运行
如果创建的项目没有 C3，请运行：
然后运行
部署应用程序并迭代
在本地预览应用程序后，你可以将其部署到 Cloudflare 页面(可通过 Direct Uploads 或 Git integration 两种方式)，并在此过程中反复进行新的更改。
疑难解答
回顾使用 next-on-pages 开发 Next.js 应用程序时可能遇到的常见错误和问题。
边缘计算时间
在 Cloudflare 页面上运行时，Next.js 项目中的所有服务器端路由必须配置为 Edge 运行时路由。你必须在每个服务器端路由中添加 export const runtime = 'edge'。
App 路由器
Not found
在构建过程中，Next.js 会为你的应用程序生成一个 not-found路由。在某些情况下，Next.js 会检测到路由需要服务器端逻辑(尤其是在根布局组件中执行计算时)，Next.js 可能会创建一个 Node.js 无服务器函数(因此与 @cloudflare/next-on-pages不兼容)。
为防止出现这种不兼容性，Cloudflare 建议始终提供一个自定义的 not-found路由，明确选择边缘运行时：
generateStaticParams `生成静态参数
在
/app目录 中进行静态网站生成 (SSG) 并使用
generateStaticParams函数时，Next.js 默认会尝试通过 Node.js 无服务器函数按需处理非静态生成路由的请求，因此这些函数与 @cloudflare/next-on-pages 不兼容。
为避免此类问题，请确保按照 上文所述，在边缘运行时选择路由(但这会使 SSG 失效，因为目前 Next.js 在边缘运行时不支持 SSG)。
或者，也可以通过指定 false
dynamicParams 来退出动态路由处理：
顶级getRequestContext(获取请求上下文
不能在路由文件的顶层调用 getRequestContext 函数，也不能在文件初始化过程中以任何方式触发函数调用。
getRequestContext 必须在请求处理流程逻辑中调用，而不是以全局/无条件的方式在导入文件后立即触发。
例如，下面是 getRequestContext 的错误用法：
上面的例子可以用下面的方法解决：
Pages 路由
getStaticPaths
在
/pages目录 中进行静态网站生成 (SSG) 并使用
getStaticPaths函数时，Next.js 默认会尝试通过 Node.js 无服务器函数按需处理对非静态生成路由的请求，因此这些函数与 @cloudflare/next-on-pages 不兼容。
为避免此类问题，请确保按照 上文所述，在边缘运行时选择路由(但这会使 SSG 失效，因为目前 Next.js 在边缘运行时不支持 SSG)。
或者，也可以通过指定
false fallback 来退出动态路由处理：
了解更多
完成本指南后，你已成功将 Next.js 网站部署到 Cloudflare Pages。要开始使用其他框架，请参阅框架指南列表