The Copy Monkey
HomeResourceTrendDemoAboutLink

Made with ❤️ by bhwang

© 2025 The Copy Monkey. All rights reserved.

Next.js cloudflare部署实践

2025-04-27

部署了好几个 Next.js 项目到 cloudflare 上了,总结下一些经验。

Cloudflare 的服务

用搜索引擎搜索 cloudflare nextjs ,至少会看到两个服务:

  • Pages
  • Workers

给人的第一感觉: Pages 应该偏向前端页面,Workers类似后端服务。 一开始就随便选了 pages 。

Pages

要将 Next.js 部署到 Pages 上,需要使用 Pages 的 @cloudflare/next-on-pages 工具。 体验下来, @cloudflare/next-on-pages 是把 Next.js 构建产物转化/编译成了 Pages 的产物,然后部署到 Pages 上。 按照官方的 迁移教程 一步步改下来就行

Edge Runtime

在修改过程中,有一步工作量最大,就是在所有页面 page.tsx 和 API route.ts 前都加上 edge 参数,表示使用 edge runtime。

export const runtime = 'edge';

这里就牵扯到一些概念

  • runtime: 比如 Node.js, Deno, Bun, workerd... 他们支持的 API 都不一样
  • edge runtime: 根据 Next.js 的说法,这是一个仅包含 API子集 的运行时(部署在边缘的运行时?)

所谓的 API子集 , 说白了就是你在 edge 环境下就不能使用某些API。 比如 fs 、 crypto 等 Node.js API。 很多第三方包都包含这些库,然后你就需要蛋疼的找替代... 比如 crypto 就要换成 web crypto 。

另外一种解决方案则是间接使用 workers ,fetch 某个 worker 或者通过 binding 调用。

这就是 Pages 和 workers 的最大区别: workers 虽然也不支持全部 Node.js API,但是官方正在努力兼容。

翻到 Pages 集成 Next.js 文档的第一部分,现在连官方都推荐后者...

You should consider using @opennextjs/cloudflare ↗, which allows you to build and deploy Next.js apps to Cloudflare Workers, use Node.js APIs that Cloudflare Workers supports, and supports additional Next.js features.

If you're coming from Vercel, you can easily migrate your Next.js app to Cloudflare by using Diverce ↗, which will automatically add OpenNext to your project and create a pull request that makes it deployable to Cloudflare.

Binding

cloudflare 里面提供了许多服务(它们都有一些免费额度)

  • KV
  • Queue
  • R2
  • ...

要想在 pages 调用,可以使用如下方式

import { getRequestContext } from '@cloudflare/next-on-pages';

const env = getRequestContext().env as any;

await env.MY_QUEUE.send({
  type: 'image',
  task_id: taskId,
  image_url: imageUrl,
});

这里 MY_QUEUE 可以在 Dashboard 后台的设置里定义,或者在 wrangler.toml 里定义。

调试

Dashboard 设置里可以选择 preview 分支,它和 production 的环境变量都是分开的,很方便。

日志

Pages 似乎没有办法直接记录,需要调用其他服务

Workers

需要通过 opennext 将 Next.js 项目迁移到 workers 上。

就冲着不需要 const runtime = 'edge' ,以后也要用这个。

opennext

按照 文档 一步步改下来就行。 记得在设置里加上这个 nodejs_compat flag 并升级 wrangler 到最新版本,就能使用某些 Node.js API,比如 crypto 。

额外功能

workers还能干很多其他事情

  • cron任务
  • queue处理
  • fetch请求处理

调试

可以分多个环境部署

日志

直接 console.log 就会记录到 Logs 里面,非常方便。

其他

本地调试

普通的业务代码还是用 next dev 来调试。但是如果代码里用了 binding (如 env.MY_QUEUE), 那就需要用 wrangler dev 来调试,体验下来比较慢。

所以如果可以,还是推荐少用 binding 方式来调用 cloudflare 的服务。

R2

对象存储:每月 10GB 的额度,算 2MB 一张图片可以存5000张。

同样的调用 R2 ,可以使用 S3 API 的方式,或者上面提到的 binding 方式。推荐前者

支持按前缀定时删除文件,建议临时文件统一前缀。

Durable Objects

适合实时性比较强,比如 IP限速器 (例子里第一个)

KV

适合不怎么改的值,比如配置信息