2026 Supabase Auth 测试邮件收不到？开发、QA、上线前分别查什么

本地开发：先看捕获，不要先查收件箱

Supabase CLI 本地邮件查看界面的默认地址是 localhost:54324。这封邮件在本地开发时会被捕获，而不是实际外发。因此，我们建议本周先按环境分流：本地流程查捕获结果；托管项目查发送配置与 Auth 日志；验收真实收件则放到自家产品的预发环境。捕获成功不等于外部送达。(Supabase 本地邮件测试文档)

正在开发注册确认或邮件登录流程的开发者，可以据此区分生成邮件与外部收件。
负责自家产品邮件验收的 QA，可以按职责记录复现条件和证据。
准备部署的独立开发者或小团队，可以用后面的清单划定上线前的验证边界。

本地没有收到真实邮件，通常不是“发信失败”，而是把本地捕获当成外部投递了。Supabase 的本地开发文档说明，CLI 会用 Mailpit 捕获 Auth 邮件，并可从本地界面查看。检查内容、变量和邮件链接可以在这里进行；但它不能证明外部收件服务接受了邮件，更不能证明邮件进入收件箱。

本地查看界面空白时，先确认本地服务正在运行，再重新执行一个明确会触发邮件的操作，例如注册并要求确认。随后检查捕获界面是否出现新邮件，以及主题、正文、链接和验证码是否符合预期。若采用本地自定义模板，还要确认本地配置文件与 HTML 模板路径对应正确；托管项目的仪表板模板不会自动替代本地配置。(Supabase 本地配置文档、Supabase 本地邮件模板文档)

QA：先确定验收的是内容、流程还是投递

QA 最容易遇到的误判，是把“邮件出现在收件箱”“点开链接后注册成功”和“邮件模板正确”当成同一项测试。它们对应不同环节。先写清本次测试要证明什么，再选择环境和证据，才能避免把本地捕获当作真实收件验收。

准备测试收件地址时，选一个团队能控制且不承载真实用户资料的地址，并为每次复测记录地址和环境。不要把同事私人邮箱当作长期测试数据池：真实注册、重置密码或邀请邮件容易混进日常收件箱，也会让复测证据难以归属。涉及测试数据中的个人信息时，可先对照测试数据与邮箱隐私注意事项检查数据暴露范围。

一个实用的 QA 记录应包含环境名称、触发时间、注册或登录操作、测试收件目标、界面结果、Auth 错误和发送服务结果。复测时尽量只改变一个变量，例如先固定模板，仅更换发送配置；否则同时改模板、回调和 SMTP，最终即使通过，也难以确定真正的修复点。

项目维护者：默认发送限制与 SMTP 交接

托管项目未必能向任意地址发测试邮件。Supabase 当前的 Auth SMTP 文档说明：没有配置自定义 SMTP 时，默认发送服务只向项目组织中预先授权的地址发送；文档当前列出的发送限制为每小时 2 封，并注明限制可能变化。默认服务也不承诺邮件投递或服务可用性。上线验收前，应重新查看文档和项目设置，而不是把这组限制当作永久规格。

对需要向团队外测试地址发信的托管预发环境，项目维护者应确认已配置适用的自定义 SMTP，再用一封可追踪的测试邮件核对 Auth 日志和服务商记录。收到 email_address_not_authorized 一类错误时，先区分默认 SMTP 的地址授权限制与自定义 SMTP 的配置故障。Supabase 的错误码文档列出该类错误与默认发送服务地址限制的关系。

日志也是区分“项目没有交接”和“服务商已经接手”的关键。若 Auth 日志显示 SMTP 配置或通信错误，先检查主机、端口、凭据及服务商限流；若服务商有对应发送记录，Supabase Auth 侧的交接并不能证明邮件一定到达最终收件箱。后续应查服务商退信记录，以及收件方的垃圾邮件或隔离规则。Supabase 的收不到 Auth 邮件排查文档也建议从 Auth 日志开始，再沿邮件服务商和收件方继续排查。

模板与回调：邮件生成不等于链接走通

负责模板和回调的开发者，应把邮件内容与应用跳转拆开验收。模板里使用的确认链接、验证码变量和回调目标，必须与当前注册或邮件登录流程相匹配。Supabase 的邮件模板说明列出 {{ .ConfirmationURL }}、{{ .Token }}、{{ .TokenHash }}、{{ .SiteURL }} 和 {{ .RedirectTo }} 等变量。变量能被填入邮件，不代表链接目标已加入允许列表，也不代表应用端已正确处理确认结果。

常见的断点有两类。第一类是目标地址不匹配：传入的回调地址不在项目允许的重定向列表中，或默认站点地址仍指向另一环境。第二类是应用接收后没有完成确认处理：路径、参数读取或后续页面逻辑与邮件实际链接不一致。按照 Supabase Auth 重定向地址文档，逐一核对项目允许的地址、调用时传入的 redirectTo，以及模板中使用的站点或跳转变量。

有个容易漏掉的边界：邮件服务商若开启链接跟踪，可能改写模板内的确认链接。这样邮件确实生成、也确实到达了，但跳转时仍可能失效。上线前应在预发环境点击邮件里的实际链接，并记录最终落地地址与应用页面结果；不要只在模板源码中确认链接长得正确。

上线负责人：真实收件验收边界

本地测试适合验证模板和流程逻辑。它无法替代外部收件验收。如果发布要求包含收件箱真实到达、发件身份展示或最终用户从邮件返回应用的路径，就需要在自家产品的预发环境完成一次端到端验证，并按该环境的发送配置检查日志和结果。

这项验收结论只适用于当次环境、地址和配置。单个测试地址收到邮件，不能推出所有用户地址都会收到；一次没有收到，也不应直接归因于 Auth 本身。保留 Auth 日志、邮件服务商记录和收件结果，才能判断问题是在项目侧、交接后，还是最终收件环节。测试期间使用不含真实用户资料的账号，也能减少个人信息混入演示和预发数据；更多边界可参考邮箱生命周期与收件管理说明。

上线前可勾选以下项目；未完成对应环境的检查，就不要把该项标为通过：

• [ ] 标记当前运行的是本地、托管开发环境，还是预发环境，并确认测试目标与环境相符。
• [ ] 本地注册后在捕获界面检查邮件，而不是等待它进入外部邮箱。
• [ ] 核对注册、邮件确认或邮件登录操作是否确实触发了预期邮件。
• [ ] 检查模板变量、确认链接、验证码内容和邮件服务商是否改写链接。
• [ ] 托管项目确认默认 SMTP 的授权范围，或核实自定义 SMTP 配置。
• [ ] 为失败操作保留 Auth 日志；若已有服务商发送记录，再查退信、抑制和隔离结果。
• [ ] 若验收目标是真实收件，使用自家产品的预发环境完成测试，并记录收件与回调结果。

按症状分流：交给正确的排查人

先保存证据，再复测；重复触发请求不会自动区分发送限制、交接失败和收件方拦截。若 QA 需要检查自家产品的真实确认邮件，可以把临时收件地址作为测试方案之一：适用于临时注册、试用或接收一次确认邮件，也能避免把工作邮箱暴露给不需要长期联系的测试流程。需要长期收信、密码找回或邮件往来的重要账户，则应使用可持续控制的邮箱，而不是临时地址。