注册验证码别再真发邮件了：Mailpit 本地邮件沙盒跑通后，用 cpolar 给测试同事临时验收

注册验证码别再真发邮件了Mailpit 本地邮件沙盒跑通后用 cpolar 给测试同事临时验收注册、找回密码、修改邮箱、订单通知这些功能开发阶段最怕两件事一是验证码真的发到用户邮箱污染测试数据二是测试同事想看邮件内容结果只能让开发截图来回确认 HTML 模板、链接和附件。更稳妥的做法是把“发邮件”这件事先关进本地沙盒应用仍然走 SMTP 发信但邮件不会离开本机而是被 Mailpit 接住再通过 Web UI 查看。这篇只做一条主线用 Docker 启动 Mailpit本地应用接入 SMTP1025在8025Web 页面里检查验证码、HTML 模板和附件需要远程验收时用 cpolar 临时暴露 Mailpit 的 Web UI。注意暴露的是查看页面不是 SMTP 端口。适用场景和边界这套方案适合开发、联调、提测前验收注册验证码、登录验证码、找回密码邮件HTML 邮件模板样式检查邮件中的按钮链接、深链、退订链接检查附件名称、大小、MIME 类型检查测试或产品不在开发机旁边需要远程看邮件效果。它不适合替代生产邮件系统也不是营销邮件发送教程。生产环境仍然应该使用正式邮件服务商、队列、重试、退信处理、监控告警和权限审计。Mailpit 在这里的角色很清楚本地邮件沙盒。1. 用 Docker 启动 Mailpit开发机上先准备 Docker然后创建一个独立容器docker run -d \ --name mailpit \ -p 127.0.0.1:1025:1025 \ -p 127.0.0.1:8025:8025 \ axllent/mailpit:latest这里有两个端口1025SMTP 入口应用把邮件发到这里8025Web UI用浏览器查看已经被 Mailpit 接住的邮件。我建议在本机绑定时写成127.0.0.1:端口:端口这样 Docker 只监听本地回环地址不会把端口直接挂到局域网所有网卡上。启动后检查容器状态docker ps --filter namemailpit看到0.0.0.0以外的监听并不是本文推荐方式。本文后面会用 cpolar 临时开放 Web UI所以本地 Docker 这一层先收紧。打开浏览器访问http://127.0.0.1:8025页面能打开说明 Mailpit 的查看端已经就绪。此时收件箱为空是正常的因为应用还没有发邮件过来。2. 让应用接入本地 SMTP 1025接下来把应用的邮件配置指向本机 Mailpit。核心配置只有几项SMTP 主机是127.0.0.1端口是1025不需要真实用户名和密码不开启 TLS。以常见环境变量为例SMTP_HOST127.0.0.1 SMTP_PORT1025 SMTP_USERNAME SMTP_PASSWORD SMTP_SECUREfalse MAIL_FROMno-replyexample.test如果是 Node.js 使用 Nodemailer可以这样写一个最小测试脚本import nodemailer from nodemailer; const transporter nodemailer.createTransport({ host: 127.0.0.1, port: 1025, secure: false, auth: undefined, }); await transporter.sendMail({ from: no-replyexample.test, to: testerexample.test, subject: 注册验证码123456, html: h2欢迎注册/h2 p你的验证码是strong123456/strong/p p验证码 10 分钟内有效。/p a hrefhttps://example.test/verify?code123456继续完成验证/a , text: 你的验证码是12345610 分钟内有效。, });如果是 Spring Boot开发环境可以用这样的配置spring: mail: host: 127.0.0.1 port: 1025 username: password: properties: mail: smtp: auth: false starttls: enable: false如果是 LaravelMAIL_MAILERsmtp MAIL_HOST127.0.0.1 MAIL_PORT1025 MAIL_USERNAMEnull MAIL_PASSWORDnull MAIL_ENCRYPTIONnull MAIL_FROM_ADDRESSno-replyexample.test MAIL_FROM_NAMELocal Demo重点不是框架而是原则开发、测试配置必须和生产配置分开。不要为了省事把生产 SMTP 用户名、密码复制进本地.env更不要把真实用户邮箱作为收件人。测试收件人可以统一使用example.test、example.com这类不会被当成真实投递目标的域名或者团队约定的脱敏测试账号。3. 在 Web UI 查看验证码、HTML 和附件应用触发注册流程后回到 Mailpit 页面刷新。新邮件会出现在左侧列表里点进去可以看几个关键点。第一看标题和收件人。注册验证码邮件的标题是否包含业务标识收件人是否是测试账号发件人是否符合产品约定。这里能直接发现“模板拿错环境变量”“收件人拼错”“标题还是英文占位文案”这类问题。第二看 HTML 预览。Mailpit 会渲染 HTML 邮件适合检查按钮颜色、段落间距、验证码是否醒目、移动端宽度是否过宽。验证码场景尤其要确认验证码数字和短信验证码规则一致过期时间文案一致页面里没有出现调试字段、内部接口地址或用户隐私信息。第三看纯文本版本。很多邮件客户端会显示纯文本 fallback如果后端只写了 HTML纯文本为空验收时就应该记录下来。验证码邮件的纯文本版本至少要包含验证码、有效期和业务说明。第四看 Headers。Headers 里可以看到From、To、Subject、Content-Type等信息。虽然本地沙盒不负责真实投递但这些字段能提前暴露编码、字符集和发件人显示名问题。第五看附件。如果邮件里带了发票、报表或导出文件可以在 Mailpit 里直接看到附件名称和类型。验收时重点检查附件是否为空文件、文件名是否包含中文乱码、是否误带内部路径或用户隐私字段。如果想快速清空收件箱Mailpit 页面里可以直接删除邮件也可以重启容器重新开始一轮干净验收docker restart mailpit需要保留现场时不要清空直接把当前 Web 页面通过 cpolar 暴露给测试同事看。4. 用 cpolar 临时暴露 Mailpit Web UI测试同事不在同一台机器上时不要把 SMTP1025暴露出去。正确做法是只开放 Mailpit 的 Web UI也就是本机8025。先确认本机访问正常curl -I http://127.0.0.1:8025返回 HTTP 响应后再启动 cpolar 隧道cpolar http 8025终端会生成一个临时公网访问地址形式类似https://xxxx.cpolar.top把这个地址发给测试或产品他们就能在浏览器里查看 Mailpit 收件箱、打开邮件、确认验证码展示、HTML 样式和附件信息。验收时建议同步说明三件事这个页面只用于查看本地沙盒邮件不要在里面输入真实用户邮箱或真实验证码验收结束后入口会关闭。如果团队要多轮验收可以让应用继续往127.0.0.1:1025发信测试同事刷新 cpolar 地址即可看到新邮件。整个过程中公网侧只有 Web 查看页SMTP 仍然留在本机不接收外部投递。验收结束后回到运行 cpolar 的终端按CtrlC关闭隧道。再检查 cpolar 进程已经退出ps aux | grep cpolar | grep -v grep如果没有输出说明临时入口已经关闭。Mailpit 容器需要继续本地开发就保留不需要时可以停止docker stop mailpit5. 一份更适合团队复用的 Docker Compose如果项目里多人都要跑同样的邮件沙盒可以放一份docker-compose.mailpit.ymlservices: mailpit: image: axllent/mailpit:latest container_name: mailpit ports: - 127.0.0.1:1025:1025 - 127.0.0.1:8025:8025 restart: unless-stopped启动docker compose -f docker-compose.mailpit.yml up -d停止docker compose -f docker-compose.mailpit.yml down然后在项目文档里写清楚开发环境邮件配置开发环境 SMTP127.0.0.1:1025 开发环境 Web UIhttp://127.0.0.1:8025 远程验收仅在需要时执行 cpolar http 8025验收结束立即关闭这样新同事接手时不需要猜端口也不会把生产邮件服务接进本地测试流程。6. 安全边界一定要写进验收说明邮件沙盒看起来只是开发工具但它里面会出现验证码、用户昵称、订单号、附件文件名和模板变量所以边界要提前讲清楚。第一SMTP1025不开放公网。它只给本机应用投递测试邮件使用不给外部系统发邮件也不接收公网请求。第二cpolar 只暴露 Web 查看页8025。测试同事拿到的是浏览器查看入口不是邮件发送能力。第三只使用测试账号和脱敏邮件。注册、找回密码、订单通知这些流程都应该走测试用户邮件正文里不要出现真实手机号、真实身份证号、真实订单地址和真实用户邮箱。第四不使用真实用户邮箱。哪怕 Mailpit 不会把邮件投递出去测试流程也不应该依赖真实用户邮箱作为收件人字段避免日志、截图、验收记录继续传播个人信息。第五不泄露生产 SMTP 密码。本地.env、Compose 文件和截图里都不应该出现生产邮件服务商的账号、授权码、API Key。第六验收结束关闭 cpolar。临时入口只服务一次验收窗口关闭以后再补充验收结论。不要把临时公网地址长期贴在群公告或项目文档里。第七长期测试环境要走正式访问控制。如果团队需要持续远程查看邮件沙盒应接入内网、VPN、基础认证、统一登录或网关权限而不是长期裸奔一个 Mailpit 页面。7. 验收清单最后给测试同事一份简单清单能让验收更聚焦触发注册后Mailpit 是否收到邮件收件人、标题、发件人显示名是否正确验证码是否清晰展示位数和有效期是否符合需求HTML 样式是否和设计稿一致移动端宽度是否正常邮件按钮链接是否指向测试环境纯文本版本是否可读附件是否存在文件名和格式是否正确邮件正文是否没有真实用户信息、内部密码、生产域名和调试字段验收结束后cpolar 隧道是否已关闭。按这套流程走开发不用把验证码截图发来发去测试和产品也能直接看真实邮件渲染效果。Mailpit 负责把邮件安全地留在本地cpolar 只在验收窗口提供临时查看入口两者职责分开既方便联调也能把误发和泄密风险压到最低。