邮件 | Web Cloudflare · MuseMVP 文档

收到第一封验证码邮件，设置发件地址，再按需自定义模板。

配置邮件后，用户就能收到注册验证码、登录验证码和密码重置邮件，联系表单也能投递消息。需要真实收件时，再接入邮件服务。

开始前准备

准备本地应用、测试收件箱和可验证的发件域名。使用 Cloudflare Email Sending；Workers 生产不支持 Resend 或 console 投递。发送额度以你的账号为准。

1. 接入邮件服务

Cloudflare Email Sending

配置发件域名，并获取你的账号所需的邮件发送权限 API Token。在 apps/web-cloudflare/.env.local 和 .dev.vars 中填写：

MAIL_PROVIDER="cloudflare"
CLOUDFLARE_ACCOUNT_ID="YOUR_ACCOUNT_ID"
CLOUDFLARE_API_TOKEN="YOUR_EMAIL_SENDING_TOKEN"
MAIL_FROM="Acme <[email protected]>"
MAIL_FROM_NEWSLETTER="Acme <[email protected]>"
CONTACT_FORM_TO="[email protected]"
NEXT_PUBLIC_EMAIL_SUPPORT="[email protected]"

生产宿主也需要设置相同的服务端凭据。上线前还要将对应服务端凭据配置到生产宿主。

2. 收到第一封邮件

重启开发服务。打开登录页，对你自己的账号请求邮箱登录验证码；也可以为已有账号测试密码找回。检查收件箱和垃圾邮件，再用收到的验证码完成对应流程。

确认结果

邮件真实到达，发件地址、产品名称和语言符合预期。
验证码可以完成对应登录或重置流程。
联系表单消息到达 CONTACT_FORM_TO。
使用 Newsletter 时，确认邮件和签名退订链接可以完成流程。

常见问题

问题	处理方式
收件箱没有邮件	检查服务端报错、服务商日志、垃圾邮件
服务商拒绝发件人	检查域名验证和 Token 权限，使用该域名的发件地址
Workers 本地正常，生产失败	检查部署密钥和 `MAIL_PROVIDER=cloudflare`；`.dev.vars` 不是生产密钥库
链接跳到 localhost	将部署环境 `NEXT_PUBLIC_SITE_URL` 改为 HTTPS origin，重新构建

自定义邮件

共享 React Email 模板在 packages/mail/src/templates/。现有 ID：emailVerification、magicLink、newsletterSignup、verificationCode、verificationCodeSignin、verificationCodeForgotPassword。

运行下面的命令预览：

pnpm --filter @musemvp/cloudflare exec email dev --dir ../../packages/mail/src/templates --port 4100

打开 **http://localhost:4100**。请用这里的明确目录：当前根 mail:preview 脚本仍指向旧模板位置。

新增模板时注册 ID，并在两语言 packages/i18n/src/translations/{en,zh}/mvp.json 添加 mail.<templateId>.subject。包内使用相对或包名导入，不导入应用 @/。

应用服务端可以这样调用：

import { sendEmail } from "@/modules/mail";

await sendEmail({
  to: user.email,
  locale,
  templateId: "verificationCodeSignin",
  context: { otp, expiresIn: 300 },
});

user、locale 和 otp 来自你的服务端流程。sendEmail() 也支持原始 subject / html / text。要发欢迎邮件，可新增模板并连接到对应事件，默认模板不包含该场景。预览检查外观，真实流程检查投递。