用 Cloudflare + Next.js 部署 MoeMail：把临时邮箱系统搭起来，其实没有想象中复杂

临时邮箱这类工具，看起来像是“小众需求”，但只要你做过产品测试、渠道注册、自动化验证，或者单纯不想把主邮箱暴露在太多场景里，就会明白它的价值。

相比传统自建邮件服务那种动辄要碰服务器、端口、反垃圾规则的复杂方案，MoeMail 这一套基于 Cloudflare + Next.js 的部署方式，明显更轻，也更适合个人站长和独立开发者。它利用 Cloudflare 的 Pages、Workers、D1 和 KV 这些能力，把“收临时邮件”这件事做成了一套相对现代、低运维成本的方案。

这篇文章，我想用尽量清晰、少踩坑的方式，把 MoeMail 的部署逻辑梳理一遍。你不需要有很重的运维背景，只要把几个关键参数准备好，再按顺序完成配置，基本就能把系统跑起来。

为什么 MoeMail 这套方案值得折腾

在开始之前，先说一句结论：MoeMail 不是传统意义上的“装个程序就完事”，它本质上是一套围绕 Cloudflare 生态构建的临时邮箱服务。

它的优势很明显：

• 无需自购服务器，整体偏 Serverless 思路
• 部署流程自动化，适合通过 GitHub Actions 一键推进
• 前后端一体化，页面和数据层都能放在 Cloudflare 上
• 支持 GitHub 登录，少做一套用户系统
• 可扩展发件能力，后续还能接入 Resend

换句话说，如果你本来就在用 Cloudflare 托管域名或站点，那 MoeMail 的上手门槛会比你想象中低不少。

一句话理解：
这是一个更偏“现代 Web 应用”的临时邮箱方案，而不是传统邮件服务器方案。

一、部署前要准备什么

正式开始前，有两样东西是前提：

1. Cloudflare 账号

你需要提前注册 Cloudflare，并且把准备用来做临时邮箱的域名 DNS 托管到 Cloudflare。

这一步很关键，因为后面的 Pages、Workers、Email Routing 都依赖 Cloudflare 生态。

2. GitHub 账号

GitHub 在这里不只是代码托管平台，它同时承担两个角色：

• 用来 Fork MoeMail 项目并触发自动化部署
• 作为网站用户的 第三方登录方式

如果你没有 GitHub 账号，这套流程基本没法顺畅走完。

二、先把 4 个关键参数准备好

很多部署失败，其实不是卡在代码，而是卡在“密钥和配置项没提前准备完整”。
在 MoeMail 里，下面这 4 个参数是核心中的核心。

1. Cloudflare API Token 和 Account ID

你需要拿到两项信息：

• Account ID
• API Token

其中，Account ID 可以在 Cloudflare 控制台的地址栏或概览页面右下角找到。

而 API Token 需要你手动创建。路径大致是：

我的个人资料 -> API 令牌

创建 Token 时要特别注意权限范围。这个 Token 至少需要有以下资源的编辑权限：

• Pages
• D1 数据库
• Workers
• KV 命名空间

如果权限不够，GitHub Actions 在自动部署阶段通常会直接失败。

2. GitHub OAuth App

因为 MoeMail 使用 GitHub 作为登录方式，所以你还需要在 GitHub 后台创建一个 OAuth App。

路径是：

Settings -> Developer settings -> OAuth Apps -> New OAuth App

创建时最关键的是两个 URL：

• Homepage URL
  填你的网站首页地址，例如：
  https://mail.你的域名.com
• Authorization callback URL
  填：
  https://mail.你的域名.com/api/auth/callback/github

创建完成后，记录好这两项：

• Client ID
• Client Secret

后面 GitHub Actions 的 Secrets 要用到。

3. AUTH_SECRET

这个值本质上就是你应用的加密密钥之一，主要用于 Session 加密。
做法很简单：生成一段足够长、足够复杂的随机字符串。

不要图省事用简单字符，更不要把它写成容易猜到的内容。

4. 一个清晰的域名规划

虽然这不算“官方列出的第四类参数”，但实际部署时我非常建议你提前想好域名结构。
比如：

• 主站：example.com
• MoeMail：mail.example.com

这样后续配置 GitHub OAuth 回调和 Cloudflare 自定义域名时，逻辑会更清楚，也更不容易填错。

三、自动化部署：把 GitHub Actions 配好

准备工作完成后，就进入真正的部署阶段。

1. Fork 官方项目

先打开 MoeMail 项目源码仓库：

beilunyang/moemail

然后点击右上角的 Fork，把项目复制到你自己的 GitHub 账号下。

2. 在仓库里添加 Secrets

进入你 Fork 后的仓库，打开：

Settings -> Secrets and variables -> Actions -> New repository secret

然后依次添加下面这些必须项，名字要完全一致：

• CLOUDFLARE_API_TOKEN
  你的 Cloudflare API Token
• CLOUDFLARE_ACCOUNT_ID
  你的 Cloudflare Account ID
• AUTH_GITHUB_ID
  GitHub OAuth 的 Client ID
• AUTH_GITHUB_SECRET
  GitHub OAuth 的 Client Secret
• AUTH_SECRET
  你自己生成的随机加密字符串

3. 可选的自定义配置

如果你希望项目更贴合自己的命名方式，还可以额外添加这些 Secrets：

• CUSTOM_DOMAIN
  自定义域名，例如：mail.你的域名.com
• PROJECT_NAME
  Cloudflare Pages 项目名，默认是 moemail
• DATABASE_NAME
  D1 数据库名称，默认是 moemail-db
• KV_NAMESPACE_NAME
  KV 命名空间名称，默认是 moemail-kv

这些不是必须，但对于后续维护会更友好。尤其是当你账号里项目比较多时，统一命名规范能省掉不少辨识成本。

4. 手动触发部署

接着来到仓库顶部的 Actions 标签页：

• 左侧选择 Deploy 工作流
• 右侧点击 Run workflow
• 手动触发部署

接下来就交给 GitHub Actions 去跑。
如果一切正常，几分钟后你会看到一条绿色打勾的记录，这意味着：

• 前端页面已部署到 Cloudflare Pages
• 后端依赖的数据资源也已完成初始化

到了这一步，网站通常已经能访问了。

四、真正决定邮件能不能收到的关键：Email Routing

这里是最容易被忽略的一步，也是最关键的一步。

很多人看到页面能打开，就以为已经部署成功。实际上，如果没有配置 Cloudflare Email Routing，MoeMail 只是“站点能访问”，并不等于“邮箱能收信”。

配置路径

回到 Cloudflare 控制台，进入你的域名管理页面，然后找到：

电子邮件 (Email) -> 电子邮件路由 (Email Routing)

开启 Catch-all

找到 Catch-all address（捕获所有地址），并启用它。

这一步的意义是：
凡是发到你域名下的任意邮箱地址，比如：

• test@你的域名.com
• hello@你的域名.com
• random123@你的域名.com

都可以被统一捕获。

把邮件转发给 Worker

接下来编辑规则，设置为：

• Action：Send to Worker
• Destination：选择自动部署生成的 Worker
  名称通常会和 email-receiver-worker 有关

保存之后，整个流程才算真正打通。

此后，发往你域名下任意地址的邮件，就会被这个 Worker 捕获，再交由 MoeMail 的网页端进行展示。

这一步不是“优化项”，而是核心功能本身。
没配好 Email Routing，前面的部署只能算完成了一半。

五、想让 MoeMail 不止能收信？可以接入 Resend

默认情况下，MoeMail 更像一个“临时收件系统”。
但如果你有进一步需求，比如希望它也具备发件能力，那么可以接入 Resend。

配置思路很简单

先去 Resend 官网注册账号，然后在控制台生成一个 API Key。

接着：

1. 打开你已经部署好的 MoeMail 网站
2. 使用 GitHub 登录
3. 第一个登录系统的用户，会自动获得最高权限角色：皇帝（Emperor）

然后进入右上角的个人中心，找到：

Resend 发件服务配置

你可以在这里：

• 开启发件服务
• 填入 Resend API Key
• 为不同等级用户设置每日发件限制

保存后刷新页面，如果当前账号有对应权限，就能在邮箱列表里看到“发送邮件”的按钮。

角色系统也是这套应用的一个亮点

MoeMail 内置了角色管理体系，比如：

• 皇帝
• 公爵
• 骑士
• 平民

这意味着它并不只是一个“自己玩”的小工具，它其实具备一定的多人使用和权限控制能力。
如果你打算把它开放给少量团队成员或朋友使用，这一点会非常实用。

角色升级

1. 成为皇帝
   • 第一个访问 /api/roles/init-emperor 接口的用户将成为皇帝，即网站所有者
   • 站点已有皇帝后，无法再提升其他用户为皇帝
2. 角色变更
   • 皇帝可以在个人中心页面将其他用户设为公爵、骑士或平民

六、部署过程中最值得注意的几个细节

实际体验下来，MoeMail 这类项目真正麻烦的地方，不在“步骤多”，而在于很多配置看似只是小细节，但一旦填错，整个流程就会卡住。

这里把几个最常见的问题单独拎出来说：

1. OAuth 回调地址一定要完全对应

GitHub OAuth 的回调地址如果写错，哪怕只是路径少了一段，登录都会失败。

尤其注意这个格式：

https://mail.你的域名.com/api/auth/callback/github

不要想当然，也不要漏掉协议头。

2. Cloudflare Token 权限不完整

这是自动部署失败的高频原因之一。
如果发现 GitHub Actions 报错，优先检查 Token 是否真的具备以下资源的编辑权限：

• Pages
• D1
• Workers
• KV

3. 站点能打开，不代表邮件功能可用

这一点前面已经强调过一次，但很值得再强调一遍。
页面访问成功，只代表前端部署完成；邮件能否收取，要看 Email Routing 是否已经正确指向 Worker。

4. 出错时优先看 GitHub Actions 日志

MoeMail 的部署过程本身已经比较自动化，所以一旦失败，最有效的排查方式通常不是“猜”，而是直接去看 GitHub Actions 的运行日志。

大部分问题都会在日志里给出比较明确的线索，比如：

• 权限不足
• Secret 缺失
• 资源创建失败
• 域名配置异常

七、这套方案适合谁

如果你问我，MoeMail 最适合什么人，我会说它尤其适合下面几类用户：

• 想搭一个个人可控的临时邮箱站点
• 已经在使用 Cloudflare 的独立开发者
• 不想维护传统邮件服务器，但又希望拥有邮件接收能力
• 希望通过 GitHub 登录 + 权限系统 管理站点用户
• 后续可能还想扩展发件能力

它不一定适合所有人。
如果你只是偶尔收一两封测试邮件，直接用现成第三方临时邮箱工具会更省事。
但如果你希望这个能力变成自己站点的一部分，甚至希望它可以服务多人，那么 MoeMail 这套架构就很有吸引力了。

MoeMail 的难点不在“技术重”，而在“配置要细”

整体看下来，MoeMail 的部署逻辑其实并不复杂，真正决定成败的，是你有没有把几个关键环节串起来：

1. 准备好 Cloudflare 与 GitHub 相关密钥
2. 在 GitHub Actions 中正确配置 Secrets
3. 完成自动化部署
4. 在 Cloudflare 中把 Email Routing 指向 Worker
5. 有需要的话，再接入 Resend 获得发件能力

从体验上说，这是一套非常符合现代独立开发工作流的方案：
前端托管、后端事件处理、数据库、KV、邮件路由，全都收敛在 Cloudflare 生态里，再通过 GitHub 完成自动化交付。

它不是零配置，也不是“点一下就全好”的傻瓜式工具，但只要你把关键参数和路由关系理清楚，部署成功之后，后续维护成本其实是比较低的。

如果你本来就想给自己的站点增加一个可控的临时邮箱系统，那么 MoeMail 值得试一次。