个人邮箱

文档
Cloudflare Workers 部署

Cloudflare Workers 部署

把个人邮箱站完整部署到 Cloudflare Workers 的最小可用流程。

适用场景

这份说明适合你准备把当前仓库完整部署到 Cloudflare：

  • Web 应用运行在 Cloudflare Workers
  • 域名托管在 Cloudflare
  • 入站邮件走 Email Routing + Email Worker
  • 附件或缓存可接 R2

如果你的目标只是尽快上线，依然建议优先考虑 Vercel + Cloudflare 的混合方案；全 Cloudflare 更统一，但部署改造也更多。

当前仓库已完成的适配

仓库里已经补上了这些基础项：

  • @opennextjs/cloudflare
  • wrangler.jsonc
  • open-next.config.ts
  • Cloudflare 预览/构建脚本
  • Prisma 的 engineType = "client"
  • @prisma/adapter-pg + pg
  • 去掉了 Vercel 专属的地理定位依赖

你可以直接用这些命令：

pnpm build
pnpm cf:build
pnpm preview
pnpm deploy

第一步：准备 Cloudflare 资源

至少准备这些资源：

  1. 一个 Cloudflare 账号
  2. 一个 Workers 项目名
  3. 一个 PostgreSQL 数据库
  4. 一个邮箱发信服务账号，例如 Brevo
  5. 一个接收附件或缓存的 R2 bucket（按需）

如果你还要接收邮件，再额外准备：

  1. Email Routing
  2. Email Worker
  3. 邮件投递接口 /api/v1/email-catcher

第二步：填写 Wrangler 配置

根目录已经有 [wrangler.jsonc](C:\Users\Books_007\Documents\New project 3\wrangler.jsonc)。

你至少要确认两处：

  1. name 把它改成你真正的 Worker 名称。

  2. services 这里的 service 要和 name 保持一致，因为它是 OpenNext 用来自引用 Worker 的绑定。

如果你后面要加 R2 缓存或附件桶，可以继续在 wrangler.jsonc 里追加 r2_buckets。

第三步：准备环境变量

本地 Cloudflare 预览建议基于 [.dev.vars.example](C:\Users\Books_007\Documents\New project 3.dev.vars.example) 新建一份 .dev.vars。

最关键的变量有：

NEXTJS_ENV=development
NEXT_PUBLIC_APP_URL=https://mail.yourdomain.com
NEXT_PUBLIC_APP_NAME=个人邮箱
AUTH_URL=https://mail.yourdomain.com
AUTH_SECRET=replace-me
DATABASE_URL=postgres://...
BREVO_API_KEY=...
EMAIL_FROM=support@yourdomain.com
EMAIL_FROM_NAME=个人邮箱

生产环境建议用 wrangler secret put 管理敏感值：

pnpm wrangler secret put AUTH_SECRET
pnpm wrangler secret put DATABASE_URL
pnpm wrangler secret put BREVO_API_KEY

第四步：本地验证

先跑常规构建：

pnpm build

如果通过，再跑 OpenNext 构建：

pnpm cf:build

Windows 注意事项

当前仓库在 Windows 本机运行 pnpm cf:build 时，可能会卡在 Next.js 复制 standalone traced files 的符号链接步骤，并报 EPERM symlink。

这不是 Cloudflare 配置本身的问题，而是 Windows 本地文件系统对这类符号链接复制比较严格。推荐做法是：

  1. 在 WSL 里执行 pnpm cf:build
  2. 或者直接把仓库推到 GitHub，让 Cloudflare 的 Linux 构建环境完成构建

也就是说：

  • pnpm build 在本机通过，说明代码层兼容基本没问题
  • pnpm cf:build 在 Windows 的 EPERM，更像本地平台限制

第五步：部署到 Cloudflare

登录 Wrangler：

pnpm wrangler login

然后部署：

pnpm deploy

首次部署前建议确认：

  1. wrangler.jsonc 里的 Worker 名称正确
  2. 所有 Secrets 都已配置
  3. 数据库可从公网访问
  4. AUTH_URL 与正式域名一致

第六步：接入邮箱链路

主站部署完成后，再接邮件功能：

  1. 域名切到 Cloudflare
  2. 开启 Email Routing
  3. 部署 Email Worker
  4. 把收件投递到 /api/v1/email-catcher
  5. 发信使用 Brevo

如果你要让附件走 R2，也记得补：

  • NEXT_PUBLIC_EMAIL_R2_DOMAIN
  • 对应的 R2 bucket / 自定义域名

现阶段已知限制

当前这套 Cloudflare 方案已经把仓库接到“可部署形态”，但还有两点你要知道：

  1. 本机 Windows 下的 pnpm cf:build 可能因为符号链接失败而中断。
  2. 数据库目前依赖 PostgreSQL，所以生产环境要保证 DATABASE_URL 可连通。

如果你下一步要继续推进，最推荐的顺序是：

  1. 先把仓库推到 GitHub
  2. 在 Cloudflare 的 Linux 构建环境里跑部署
  3. 再接真实数据库和邮件链路