支持的版本和特性

操作系统

@cloudflare/next-on-pages 可以在 Linux、Mac OS 和 Windows 上运行，但是我们不建议在 Windows 上使用，因为我们发现其中一个 CLI 的依赖项，Vercel CLI（用于构建 Next.js 应用程序）似乎在 Windows 上不可靠。如果您需要在 Windows 上运行 @cloudflare/next-on-pages，我们建议您在 Windows 用于 Linux 的子系统下运行它。

支持的 Next.js 版本

@cloudflare/next-on-pages 支持 Next.js 13 和 14 的所有次要和修订版本。我们定期进行手动和自动化测试，以确保其兼容性。

Next.js 的 Canary 版本目前未进行活动测试，我们目前不扩展对这些版本的支持。

Node.js

Next.js 为应用程序的路由提供两种不同的运行时：Node.js 和 Edge。

使用 Node.js 运行时的路由将被构建为 Node.js 无服务器函数，这些函数与 Cloudflare 网络不兼容，因此在使用 @cloudflare/next-on-pages 时仅支持使用 Edge 运行时的路由。

Cloudflare Workers 运行时支持某些 Node.js API，但是 Next.js 在其 Edge 运行时目前仅支持子集，因此目前 @cloudflare/next-on-pages 仅支持以下 Node.js 内置模块：

• buffer
• events
• assert
• util
• async_hooks

外部软件包

您可以自由地在 Next.js 应用程序中使用任何外部 npm 软件包，前提是它们不会使用：

• 不支持的 Node.js API（参见上文）
• 由于安全问题而被 Cloudflare 禁用的 JavaScript API
• @cloudflare/next-on-pages 不支持的功能（参见下文）

支持的功能

路由器

页面和应用程序路由器都受支持，但我们建议使用应用程序路由器，因为页面路由器中有一些不支持的功能（包括自定义错误页面），并且由于后者不是 Next.js 团队推荐的路由器，因此很可能不会对其进行改善/开发，以便我们增加对其的支持。

应用程序路由器应该完全受支持，但是由于 Vercel 的实现细节而超出我们控制范围的一些功能目前不受支持，例如具有服务器端运行时逻辑的自定义未找到页面。

要了解路由器的最新状态和可能缺少的功能，您可以查看我们的 GitHub 应用程序路由器和页面路由器问题。

构建输出配置

以下选项来自 Vercel 构建输出 API（v3）文档：

• ✅：已支持
• 🔄：目前不支持，但可能会在未来添加支持
• ❌：不支持，且不太可能在未来添加支持
• 1 - images：如果要使用 next/image，有两个选项：允许库处理传入的请求，或使用自定义加载器。在路由器中拦截请求并尝试使用图像大小调整（由于 Pages 的限制，目前无法使用图像大小调整），如果图像大小调整不可用，则回退到获取常规图像 URL。或者，您可以提供自己的自定义加载器，并按照Cloudflare 的图像大小调整文档使用 Cloudflare 图像大小调整。

next.config.mjs 属性

以下选项来自 Next.js 的 next.config.js 应用程序和页面文档。

• ✅：已支持
• 🔄：目前不支持，但可能会在未来添加支持
• ❌：不支持，且不太可能在未来添加支持
• N/A：不适用
• 1 - compress：Cloudflare 会自动应用 gzip 或 brotli 压缩。在使用 Wrangler 进行本地开发时，不会应用压缩。
• 2 - dev indicators：如果您使用 wrangler pages dev 进行开发，则每次都会刷新您的应用程序，因此不会显示开发指示器。如果您使用 next dev 在本地运行应用程序，则此选项可以正常工作。
• 3 - setting custom build directory：使用 @cloudflare/next-on-pages 构建的应用程序不依赖于 .next 目录，因此此选项并不适用（相反，可以使用 --outdir 标志来实现 @cloudflare/next-on-pages 的效果）。
• 4 - exportPathMap：用于 SSG 的选项，对于使用 @cloudflare/next-on-pages 构建的应用程序不适用。
• 5 - logging：如果您使用 wrangler pages dev 进行开发，则不会应用额外的日志记录（因为您实际上正在运行生产版本）。如果您使用 next dev 在本地运行应用程序，则此选项可以正常工作。
• 6 - onDemandEntries：不适用，因为它是一个用于开发中的 Next.js 服务器的选项，我们并不依赖于它。
• 7 - optimizePackageImports：@cloudflare/next-on-pages 会执行块 deduplication 并提供基于模块惰性加载的实现。因此，对 CLI 生成的输出，应用 optimizePackageImports 不会对其产生影响。但是，此配置仍然可以用于加快构建过程（无论是在运行 next dev 还是在生成生产版本时）。
• 8 - output：@cloudflare/next-on-pages 与标准的 Next.js 输出一起工作，而 standalone 则与之不兼容。export 用于生成静态网站，而不需要 @cloudflare/next-on-pages 来运行。
• 9 - Partial Prerendering (experimental)：如果官方Next.js 文档中的描述是正确的话，那么 Partial Prerendering 是专为 Node.js 运行时设计的。因此，它与 @cloudflare/next-on-pages（仅在边缘运行时上工作）基本不兼容。
• 10 - productionBrowserSourceMaps：@cloudflare/next-on-pages 执行的 webpack 块 deduplication 目前不会保留源映射，因此无法实现此选项。在未来，我们可能会尝试保留源映射，在这种情况下，支持此选项应该很简单。
• 11 - reactStrictMode：我们目前以此方式构建应用程序，使得 react strict mode（作为本地开发特性）无法正常工作。如果我们能够让 strict mode 正常工作，则此选项很可能也能够正常工作。
• 12 - runtime configuration：我们可以考虑实现 runtime 配置，但是可能不值得，因为它是一个遗留配置，而应该使用环境变量。
• 13 - serverComponentsExternalPackages：此选项是用于在 Node.js 上运行的应用程序的，因此对于在 Cloudflare Pages 上运行的应用程序不相关。

国际化

除了上面提到的 next.config.js 属性之外，还有一个名为 i18n 的属性，它也得到了完全的支持。这意味着 @cloudflare/next-on-pages 支持 Next.js 的内置国际化系统。有关该选项的更多详细信息，请参阅Next.js 国际化文档。

渲染和数据获取

增量静态再生

增量静态再生（ISR）是 Next.js 中的一种渲染模式，它允许您自动缓存并定期使用新数据再生页面。Next.js 不支持为边缘运行时构建 ISR 页面，因此应该将页面更改为使用服务器端渲染（SSR）。

ISR 页面由 Vercel CLI 生成，以创建 Vercel Prerender 函数。这些是可以在缓存页面时在后台调用的 Node.js 无服务器函数。目前不能将其与 Cloudflare Pages 一起使用，且与边缘运行时不兼容。

如果 Vercel 构建过程为您的应用程序生成了预渲染的页面，那么 @cloudflare/next-on-pages 将使用由构建过程生成的静态备用文件，以便您的应用程序仍然可以正确地提供 ISR/预渲染的页面（但没有再生的方面）。

动态处理静态路由

@cloudflare/next-on-pages 支持标准的静态生成路由，但不支持动态 Node.js 基础的按需处理此类路由。

有关更多详细信息，请参见：

• troubleshooting generateStaticParams
• troubleshooting getStaticPaths

缓存和数据再验证

再验证和 next/cache 在 Cloudflare Pages 上受到支持，并且可以使用各种绑定。有关更多信息，请参阅我们的缓存文档。