Ghost 开发环境邮件接收与测试实战：Mailpit 本地捕获与 Mailgun 真实投递-港品优选

Ghost 开发环境邮件接收与测试实战：Mailpit 本地捕获与 Mailgun 真实投递

【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost

本篇指南以 docs/contributing/testing-email.md 为核心骨架，结合 Ghost monorepo 中 Docker 编排与后端配置源码，系统讲解开发者在 Ghost 项目中进行邮件功能开发与测试的两条路径：默认通过 Mailpit 在本地捕获所有外发邮件、零配置查看测试收件箱；以及当行为真正依赖外部邮件服务商时，如何接入 Mailgun 进行事务性邮件与 Newsletter 群发邮件的真实投递验证。读完本文，你将掌握 Mailpit 与 Ghost 开发容器的连接方式、SMTP 配置项在源码中的落点，以及 Mailgun 沙盒域名的使用限制与凭据安全实践。

先理解 Ghost 的两套邮件发送通道

在进入测试操作之前，有必要先区分 Ghost 后端中两条互相独立的邮件通道，这是理解"为什么有的配置写在mail下、有的写在别处"的关键：

事务性邮件（transactional email）：由 Ghost 核心的mail配置驱动，走标准 SMTP，用于发送欢迎邮件、密码重置、员工验证码等系统通知。对应配置项在 config.development.json 中有完整的默认示例。
群发/订阅邮件（bulk email）：Newsletter 批量投递由 Ghost 独立的 bulk email 服务负责，走的是单独的 Mailgun 相关设置，与事务性邮件的 SMTP 设置彼此独立。

这条边界在默认配置中也有印证：defaults.json 中的bulkEmail.batchSize（默认 1000）定义了批量发送的批次粒度，属于邮件队列处理逻辑；而真正的"发送给谁、怎么发"则取决于你在设置里为 Newsletter 投递单独配置的 Mailgun 凭据。因此，文档中"测试事务性邮件投递就配置 SMTP、测试 Newsletter 投递就配置 Mailgun"的说法，正是对应这两条通道。

本地开发默认方案：Mailpit 捕获一切外发邮件

一条命令启动完整的邮件捕获环境

Ghost 的开发环境在启动时就会一并拉起 Mailpit。在仓库根目录运行：

pnpm dev

开发站点发出的所有邮件都不会真正送达收件人，而是被 Mailpit 捕获并展示在 Web 收件界面 http://localhost:8025 上。Docker 开发编排会自动把 Ghost 与 Mailpit 连接起来，无需任何手工配置。

这种"捕获而非投递"的能力来自 compose.dev.yaml 中定义的mailpit服务：

使用镜像axllent/mailpit（官方 Mailpit 镜像，带有 sha256 摘要锁定，保证可复现）；
1025端口映射到容器内 1025，即 SMTP 接收端口，供 Ghost 投递邮件；
8025端口映射到容器内 8025，是 Mailpit 的 Web 收件箱界面；
额外将8026也映射到 8025，专门供 e2e 测试复用（下文会展开）；
配置了健康检查：通过wget探测http://localhost:8025确认服务就绪，Ghost 主容器depends_on该健康检查，从而保证"邮件服务先于 Ghost 可用"。

启动后打开 http://localhost:8025，即可看到 Mailpit 提供的收件箱 Web 界面，所有来自开发站点的邮件（HTML 与纯文本内容）都会出现在这里，方便你核对主题、正文、收件人等关键信息。

Ghost 是如何被"自动连上" Mailpit 的

"自动连接"并非魔法，源码可以清晰地看到两层接线逻辑。

第一层是 Docker 编排注入的环境变量。在 compose.dev.yaml 中，ghost-dev服务被注入了这样三个变量：

mail__transport: SMTP mail__options__host: mailpit mail__options__port: 1025

mailpit既是容器名也是 compose 网络内的主机名，所以 Ghost 容器只需以mailpit:1025作为 SMTP 出口即可命中 Mailpit 容器，完全不需要暴露公网地址。

第二层是 Ghost 自身的配置体系。即便不依赖 Docker 环境变量，纯本机开发也默认指向本机 1025 端口。查看开发环境默认配置 config.development.json：

"mail": { "from": "test@example.com", "transport": "SMTP", "options": { "host": "127.0.0.1", "port": 1025, "auth": { "user": "user", "pass": "unsecure" } } }

mail.transport固定为"SMTP"，表明走 SMTP 协议投递；
mail.options.host/mail.options.port指向本机 1025——正是 Mailpit 监听端口；
mail.from设为test@example.com，即开发环境下所有邮件的默认发件人；
这里的auth.user/auth.pass仅为占位凭据，Mailpit 默认并不强制校验，因此开发场景下可直接连通。

同时可以留意仓库中还存在同目录的 config.development.docker.json，其中同样声明了"transport": "SMTP"——这表明 Ghost 的配置加载器会根据环境选择不同的配置叠加层，而"开发环境使用 SMTP 接本机 Mailpit"这一约定在纯本地与 Docker 两种开发方式下都被贯彻。

值得一提的是，Ghost 配置支持以环境变量 +__分隔符覆盖任意嵌套键（例如mail__options__host实际对应mail.options.host）。这套机制正是 compose 文件与 e2e 测试可以零散改配置的原因，也是你在不修改代码的情况下临时指向其他 SMTP 服务的手段。

测试场景中的 Mailpit：e2e 基础设施的复用方式

Mailpit 不只服务于手动的pnpm dev调试，它也是 Ghost e2e 测试基建的一部分，这能帮助你理解测试时"邮件被发到了哪里、如何断言"。

在 e2e 环境中，测试使用的 Ghost 实例同样被注入指向 Mailpit 的环境变量。见 e2e/helpers/environment/constants.ts：

'mail__options__host=ghost-dev-mailpit',

也就是说，测试实例与手动开发实例共用同一个 Mailpit 容器，只是 SMTP 指向同一服务。而 e2e/helpers/services/email/mail-pit.ts 则给出了客户端基地址：http://localhost:8026——这正是 compose 文件中把 8026 映射到 8025 的原因：e2e 测试通过 Mailpit 的 HTTP API 读取、校验收件箱内容。

更值得关注的是 e2e/helpers/services/mailgun/fake-mailgun-server.ts：为了不依赖外部服务，仓库还实现了本地假 Mailgun 服务器，它默认以http://localhost:8025作为 Mailpit 地址，收到请求后会构造投递载荷并调用 Mailpit 的/api/v1/send接口把邮件写入收件箱（见该文件L189-L203）。从这条调用链可以推断：在仓库的 e2e 体系中，无论是 Mailpit 直接接收还是"假 Mailgun 转发"，最终邮件都会落到同一个 Mailpit 收件箱，从而让测试断言集中在单一、确定性的数据源上。

docker 侧的收尾命令也很直接，例如基础设施启停脚本 e2e/scripts/infra-up.sh（mysql redis mailpit）与 e2e/scripts/infra-down.sh（还会一并清理analytics、tinybird-local等），表明 Mailpit 是这套测试基础设施中默认启用的成员。

真实投递测试：接入 Mailgun

多数开发与测试都不需要真实投递，但如果你要验证的功能依赖外部邮件服务商的行为（例如投递延迟、退信处理、链接点击追踪与邮件服务商的打开率上报等），就需要让邮件真正发出去。此时有两类设置需要区分：

1. 事务性邮件：把`mail`配置改为真实 SMTP

测试事务性邮件的真实投递，需要把 Ghost 的mail设置从"指向 Mailpit"改为指向真实的 SMTP 提供商。你既可以直接以 Mailgun 提供的 SMTP 端点作为mail的 transport options，也可以使用任何其他 SMTP 服务。核心仍是前文那组键，按实际凭据替换即可：

"mail": { "from": "you@your-domain.com", "transport": "SMTP", "options": { "host": "smtp.example-provider.com", "port": 587, "secure": true, "auth": { "user": "YOUR_SMTP_USERNAME", "pass": "YOUR_SMTP_PASSWORD" } } }

说明：port、secure、auth等参数按你所选 SMTP 服务商的要求填写，示例仅为结构示意。非 Docker 开发环境下，可将这段配置写入本地的环境覆盖配置或通过mail__options__*环境变量注入。

2. Newsletter 群发：配置 bulk email 服务独立的 Mailgun 设置

若要测试 Newsletter 批量发送，需要单独为 Ghost 的 bulk email 服务配置 Mailgun 设置——这与上文mail的事务性 SMTP 配置互不相干。仓库根目录同时提供了 compose.dev.mailgun.yaml，说明针对"使用 Mailgun 的真实/模拟投递环境"仓库有专门的可组合开发编排，供有需要时叠加启动。

Mailgun 沙盒域名的硬性限制

测试时最容易踩的坑是沙盒域名约束：Mailgun 的沙盒域名只能向那些已经添加到 Mailgun 账号中并完成验证的收件人发送邮件。换言之，即便配置完全正确，只要收件地址未被你在 Mailgun 后台添加并验证，投递也会失败。因此在首次接入测试前，务必先在 Mailgun 中添加并验证若干测试收件邮箱，再用它们去触发 Ghost 的邮件。

凭据安全：只进本地，绝不入库

无论使用哪种 Mailgun 配置，凭据都应只保存在你的本地配置中，绝不要提交进仓库。Ghost 的配置体系天然支持这一点：

Docker 化开发时，敏感值通过环境变量传入（compose 文件中的mail__transport等只属于非敏感结构性配置）；
纯本地开发时，把含真实用户名/密码的覆盖配置放在不会被版本控制跟踪的本地文件，或用MAIL_OPTIONS_AUTH_USER之类的环境变量形式注入；
仓库中 config.development.json 仅保留了user/unsecure这类占位值，正是因为真实凭据不该进入源码。

如何选择：Mailpit 还是 Mailgun

官方文档给出的取舍标准非常清晰，可作为日常开发的原则：

大多数开发都不需要真实投递。请使用 Mailpit，除非你正在测试的行为本身依赖外部服务商。

据此可总结出选择矩阵：

场景	推荐方案	理由
开发邮件模板、校验正文/收件人/主题	Mailpit（默认，零配置）	邮件被本地捕获，界面即时查看，速度快、无外部依赖
e2e 自动化断言邮件内容	Mailpit（8026 端口 HTTP API）	收件箱数据源单一确定，可编程校验，无需外网
验证发送成功率、退信、打开/点击追踪等依赖服务商的行为	Mailgun（真实或本地 fake server）	只有真实投递链路才能暴露服务商侧行为
验证 Mailgun API 集成代码本身	fake-mailgun-server + Mailpit	本地即可覆盖，避免测试受网络与限额影响

从仓库的测试设施看，Ghost 团队对"尽量不依赖外部服务商"的取向非常明确：e2e 默认基础设施里，Mailpit 始终在列，而 Mailgun 的真实调用则由 fake-mailgun-server 在本地模拟，仅在行为确实需要真实服务商时才切换。这条经验同样适用于你自己的日常开发。

企业官网建设流程全解析