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 emailNewsletter 批量投递由 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: 1025mailpit既是容器名也是 compose 网络内的主机名所以 Ghost 容器只需以mailpit:1025作为 SMTP 出口即可命中 Mailpit 容器完全不需要暴露公网地址。第二层是 Ghost 自身的配置体系。即便不依赖 Docker 环境变量纯本机开发也默认指向本机 1025 端口。查看开发环境默认配置 config.development.jsonmail: { from: testexample.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设为testexample.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 服务的手段。测试场景中的 Mailpite2e 基础设施的复用方式Mailpit 不只服务于手动的pnpm dev调试它也是 Ghost e2e 测试基建的一部分这能帮助你理解测试时邮件被发到了哪里、如何断言。在 e2e 环境中测试使用的 Ghost 实例同样被注入指向 Mailpit 的环境变量。见 e2e/helpers/environment/constants.tsmail__options__hostghost-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.shmysql 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: youyour-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 自动化断言邮件内容Mailpit8026 端口 HTTP API收件箱数据源单一确定可编程校验无需外网验证发送成功率、退信、打开/点击追踪等依赖服务商的行为Mailgun真实或本地 fake server只有真实投递链路才能暴露服务商侧行为验证 Mailgun API 集成代码本身fake-mailgun-server Mailpit本地即可覆盖避免测试受网络与限额影响从仓库的测试设施看Ghost 团队对尽量不依赖外部服务商的取向非常明确e2e 默认基础设施里Mailpit 始终在列而 Mailgun 的真实调用则由 fake-mailgun-server 在本地模拟仅在行为确实需要真实服务商时才切换。这条经验同样适用于你自己的日常开发。相关资源索引围绕本文主题可在仓库中继续深入查看以下文件原始贡献者文档docs/contributing/testing-email.mdMailpit 服务与端口定义、Ghost 环境变量注入compose.dev.yaml本地开发邮件默认配置from/transport/options/authghost/core/core/shared/config/env/config.development.jsonDocker 开发配置层ghost/core/core/shared/config/env/config.development.docker.json全局默认值中的 bulk email 批次等设置ghost/core/core/shared/config/defaults.jsone2e 邮件基础设施Mailpit 客户端、假 Mailgun 服务器、环境变量注入e2e/helpers/services/email/mail-pit.ts、e2e/helpers/services/mailgun/fake-mailgun-server.ts、e2e/helpers/environment/constants.tsMailgun 组合开发编排compose.dev.mailgun.yaml【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 emailNewsletter 批量投递由 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: 1025mailpit既是容器名也是 compose 网络内的主机名所以 Ghost 容器只需以mailpit:1025作为 SMTP 出口即可命中 Mailpit 容器完全不需要暴露公网地址。第二层是 Ghost 自身的配置体系。即便不依赖 Docker 环境变量纯本机开发也默认指向本机 1025 端口。查看开发环境默认配置 config.development.jsonmail: { from: testexample.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设为testexample.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 服务的手段。测试场景中的 Mailpite2e 基础设施的复用方式Mailpit 不只服务于手动的pnpm dev调试它也是 Ghost e2e 测试基建的一部分这能帮助你理解测试时邮件被发到了哪里、如何断言。在 e2e 环境中测试使用的 Ghost 实例同样被注入指向 Mailpit 的环境变量。见 e2e/helpers/environment/constants.tsmail__options__hostghost-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.shmysql 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: youyour-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 自动化断言邮件内容Mailpit8026 端口 HTTP API收件箱数据源单一确定可编程校验无需外网验证发送成功率、退信、打开/点击追踪等依赖服务商的行为Mailgun真实或本地 fake server只有真实投递链路才能暴露服务商侧行为验证 Mailgun API 集成代码本身fake-mailgun-server Mailpit本地即可覆盖避免测试受网络与限额影响从仓库的测试设施看Ghost 团队对尽量不依赖外部服务商的取向非常明确e2e 默认基础设施里Mailpit 始终在列而 Mailgun 的真实调用则由 fake-mailgun-server 在本地模拟仅在行为确实需要真实服务商时才切换。这条经验同样适用于你自己的日常开发。相关资源索引围绕本文主题可在仓库中继续深入查看以下文件原始贡献者文档docs/contributing/testing-email.mdMailpit 服务与端口定义、Ghost 环境变量注入compose.dev.yaml本地开发邮件默认配置from/transport/options/authghost/core/core/shared/config/env/config.development.jsonDocker 开发配置层ghost/core/core/shared/config/env/config.development.docker.json全局默认值中的 bulk email 批次等设置ghost/core/core/shared/config/defaults.jsone2e 邮件基础设施Mailpit 客户端、假 Mailgun 服务器、环境变量注入e2e/helpers/services/email/mail-pit.ts、e2e/helpers/services/mailgun/fake-mailgun-server.ts、e2e/helpers/environment/constants.tsMailgun 组合开发编排compose.dev.mailgun.yaml【免费下载链接】GhostIndependent technology for modern publishing, memberships, subscriptions and newsletters.项目地址: https://gitcode.com/GitHub_Trending/gh/Ghost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考