RedwoodJS Mailer 全指南：从模板渲染、多 Provider 投递到测试与开发沙箱

后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载导读RedwoodJS Mailer 是 RedwoodJS 框架内置的端到端邮件解决方案它把「邮件模板渲染」与「邮件投递」彻底解耦为renderer渲染器与handler处理器两层抽象前者负责把 React 组件变成可供发送的 HTML/纯文本字符串后者负责把渲染结果交给 Nodemailer、Amazon SES、Resend 等真实投递服务。本文将基于 mailer.md 的完整内容结合仓库中packages/mailer的源码实现系统讲解 Mailer 的架构、yarn rw setup mailer初始化流程、mailer.send的实战用法、test/development/production 三种模式的行为差异以及如何与 RedwoodJS Studio 的模板预览和本地收件箱协作。设计目标为什么要单独做一个 MailerRedwoodJS 设计 Mailer 时遵循一个核心理念发送邮件不只是「发出」这么简单投递环节与内容准备环节同样重要。围绕这个理念Mailer 被要求满足以下能力与 mailer.md 一一对应支持 Resend、SendGrid、Postmark、Amazon SES 等主流第三方邮件服务支持以 Nodemailer 作为自托管的开源方案按用例选择不同的 Provider例如事务邮件走 Resend、摘要邮件走 SES单封邮件可以显式指定投递方式在开发与测试环境中以「沙箱」方式安全发送避免邮件意外泄漏到真实收件箱邮件可同时包含文本与 HTML并基于 React Email、MJML 等流行工具编写模板未来可扩展更多方式可做单元测试校验 to、from、cc、subject、正文等字段与 RedwoodJS Studio 集成用于设计模板与实时预览。因此RedwoodJS Mailer 不是「仅仅发一封邮件」的工具而是一套完整的邮件设计、开发与测试端到端套件。架构概览Renderer 与 Handler 两层抽象Mailer 的核心由两部分组成见 mailer.mdRenderer渲染器把 React 组件转换为可发送的文本或 HTML 字符串Handler处理器接收渲染后的内容并将其交给实际的投递服务Nodemailer、SES 等发给收件人。在源码层面这两类抽象分别定义在 handler.ts 与 renderer.ts 中AbstractMailHandler要求实现send(renderedContent, sendOptions, handlerOptions?, utilities?)与internal()两个方法AbstractMailRenderer要求实现render(template, options, utilities?)与internal()两个方法。Mailer主类见 mailer.ts持有handlers、renderers、defaults与mode四个关键状态并在构造时完成模式判定与配置校验。官方 Renderer当前仓库内置两个 renderer见 mailer.mdreact-email renderer基于 React EmailSupportedOutputFormats为both | html | text默认输出both。源码中通过react-email/render的render函数分别生成 pretty HTMLplainText: false与纯文本plainText: truemjml-react renderer基于 MJMLSupportedOutputFormats仅支持html通过renderToMjml与mjml2html生成 HTML且若renderingResult.errors非空会直接抛出错误。:::important 提示 邮件客户端对 HTML 的渲染表现差异极大这是业界公认的痛点文档建议使用成熟的 React 邮件组件库编写模板以产出在各类客户端下渲染一致的邮件。 :::官方 Handler当前仓库内置四个 handler见 mailer.mdin-memory handler内存处理器通常用于测试。源码中维护一个inbox数组send时把完整发送选项与渲染后的文本/HTML 内容压入 inbox并返回messageID: in-memory-N同时提供clearInbox()方法nodemailer handler基于 Nodemailer。HandlerConfig.transport可以是 SMTP 传输配置对象、SMTPTransport.Options或连接字符串HandlerOptions即nodemailer.SendMailOptions在调用sendMail时以展开方式覆盖基础发送选项studio handler把邮件发送到 RedwoodJS Studio 内置的本地 SMTP 收件箱内部实际复用了 NodemailerHandlerhostlocalhost、port4319、secure: false并在发送失败时打印引导信息提示使用yarn rw studio查看resend handler基于 Resend SDK构造函数接收{ apiToken }发送时会把字符串类型的附件内容转换为 utf8 Buffer 再提交并透传tags等 Resend 专属选项。除此之外社区还维护了大量第三方 renderer 与 handler可以在 npm、RedwoodJS 论坛等社区渠道中搜索获取。关键配置文件与目录约定Mailer 的核心配置文件是api/src/lib/mailer.tsyarn rw setup mailer生成的内容与 mailer.ts.template 完全一致import { Mailer } from redwoodjs/mailer-core import { NodemailerMailHandler } from redwoodjs/mailer-handler-nodemailer import { ReactEmailRenderer } from redwoodjs/mailer-renderer-react-email import { logger } from src/lib/logger export const mailer new Mailer({ handling: { handlers: { // TODO: Update this handler config or switch it out for a different handler completely nodemailer: new NodemailerMailHandler({ transport: { host: localhost, port: 4319, secure: false, }, }), }, default: nodemailer, }, rendering: { renderers: { reactEmail: new ReactEmailRenderer(), }, default: reactEmail, }, logger, })配置结构说明与 types.ts 中的MailerConfig类型对应handling.handlers对象key 是任意自定义名称value 是 handler 实例handling.default生产环境默认使用的 handler key必填。源码 mailer.ts 中若未配置会抛出No default handler configured若指向未注册的 handler 会抛出The specified default handler ... is not definedrendering.renderers对象key 为任意名称value 为 renderer 实例rendering.default生产环境默认使用的 renderer key必填校验逻辑同上defaults可选的默认发送选项详见下文test/development可选的模式级配置logger可选的日志器未提供时降级为console源码中会用.child({ module: mailer })派生子日志器。另外Mailer 约定将邮件 React 组件放在api/src/mail目录下例如欢迎邮件的组件路径应为api/src/mail/Welcome/Welcome.tsx。Mailer 完整配置参数速查配置项类型必填说明handling.handlersRecordstring, AbstractMailHandler是注册的全部 handlerkey 为自定义名handling.defaultstring是生产模式默认 handlerhandling.optionsRecordstring, HandlerOptions否各 handler 的默认 handlerOptions发送时与调用方传入的选项做浅合并rendering.renderersRecordstring, AbstractMailRenderer是注册的全部 rendererkey 为自定义名rendering.defaultstring是生产模式默认 rendererrendering.optionsRecordstring, RendererOptions否各 renderer 的默认渲染选项defaultsPartialMailBasicSendOptions否全局默认发送选项test.whenboolean \| () boolean否判定是否进入测试模式缺省为NODE_ENV testtest.handlerstring \| null否测试模式使用的 handler缺省尝试自动加载 in-memory handlerdevelopment.whenboolean \| () boolean否判定是否进入开发模式缺省为NODE_ENV ! productiondevelopment.handlerstring \| null否开发模式使用的 handler缺省尝试自动加载 studio handlerloggerLogger \| Console否日志器缺省为consoletest.handler/development.handler设为null表示显式关闭该模式下的邮件处理no-op这一点在源码中体现为send时若handlerKey null直接返回空结果mailer.ts。快速开始yarn rw setup mailer新创建的 RedwoodJS 应用默认不会安装 Mailer需要执行 CLI 命令初始化见 mailer.mdyarn rw setup mailer该命令源码位于 packages/cli/src/commands/setup/mailer会完成三件事生成api/src/lib/mailer.ts配置文件内容即上文模板安装redwoodjs/mailer-core、redwoodjs/mailer-handler-nodemailer、redwoodjs/mailer-renderer-react-email等运行时依赖把redwoodjs/mailer-handler-in-memory作为devDependency自动加入供测试模式使用。实战用法在 Service 中发送邮件以教程中的博客站点为例假设我们实现了「联系我们」功能表单收集 name、email、message 并写入数据库现在希望把每次提交同时抄送一封到内部收件箱见 mailer.md。在api/src/services/contacts.ts中更新 Serviceimport { mailer } from src/lib/mailer import { ContactUsEmail } from src/mail/Example/Example // ... export const createContact: MutationResolvers[createContact] async ({ input, }) { const contact await db.contact.create({ data: input, }) // Send email await mailer.send( ContactUsEmail({ name: input.name, email: input.email, // Note the date is hardcoded here for the sake of test snapshot consistency when: new Date(0).toLocaleString(), }), { to: inboxexample.com, subject: New Contact Us Submission, replyTo: input.email, from: contact-usexample.com, } ) return contact }这段代码做了两件事从src/lib/mailer导入 Mailer 实例从src/mail/Example/Example导入邮件模板组件调用mailer.send(template, sendOptions)第一个参数是模板组件可传入基于用户输入的 props第二个参数是发送选项指定 to、from、subject 等。发送选项详解mailer.send的发送选项对应MailSendOptions类型见 types.ts常用字段如下字段类型说明toMailAddress \| MailAddress[]必填收件人MailAddress可以是字符串或{ name?, address }cc/bccMailAddress \| MailAddress[]可选抄送/密送fromMailAddress发件人可被defaults.from兜底replyToMailAddress回复地址subjectstring必填主题headersRecordstring, string自定义邮件头attachmentsMailAttachment[]附件{ filename?, path?, content? }handlerstring指定本次发送使用的 handler覆盖默认rendererstring指定本次发送使用的 renderer覆盖默认邮件地址既可以直接传字符串inboxexample.com也可以传{ name: Redwood, address: helloredwoodjs.com }对象源码 utils.ts 中的convertAddress会把后者规范化为name address格式。使用 defaults 设置全局默认值上例中replyTo是为了满足业务逻辑而单独指定的。但如果大多数邮件都想默认设置replyTo: no-replyexample.com就不必每封邮件重复书写而是在api/src/lib/mailer.ts的配置中声明defaultsdefaults: { replyTo: no-replyexample.com, },在底层extractDefaultsutils.ts会在构造时把defaults中的地址统一转换为字符串格式并补齐空数组每次发送时constructCompleteSendOptionsutils.ts会把单次发送选项与defaults合并规则是「调用方显式传入的选项优先未传入的字段回落到 defaults」——例如未传cc时使用defaults.cc、未传from时使用defaults.from。需要特别注意的是合并校验逻辑to、subject、from三个字段是强制的。如果既没在发送选项中传入、也没有在defaults中配置会分别抛出Missing from address、Missing subject、Missing to address错误。环境模式test / development / productionMailer 会在创建时根据条件自动判定当前所处模式mailer.tsmode只有三种取值见 types.tstest | development | production。不同模式下即使调用了相同的send邮件也会被路由到不同的 handler从而保证开发与测试过程中不会意外发出真实邮件。Testing 模式当NODE_ENV为test时进入测试模式。此模式下所有邮件都会改走测试 handler而忽略生产默认 handler 以及send/sendWithoutRendering调用中显式指定的 handler见 mailer.md。默认行为Mailer 创建时会尝试加载redwoodjs/mailer-handler-in-memory包若可用则以 InMemoryMailHandler 作为测试 handler否则测试 handler 变为什么都不做的 no-op。yarn rw setup mailer已自动把该包加入 devDependencies。这一点在源码 mailer.ts 中得到印证require(redwoodjs/mailer-handler-in-memory)失败时会记录警告日志。如需手动控制测试模式行为在mailer.ts中加入test: { when: process.env.NODE_ENV test, handler: someOtherHandler, }when可以是布尔值也可以是返回布尔值的函数决定 Mailer 创建时是否进入测试模式handler指定测试模式使用的 handler必须是handling.handlers中已注册的名称设为null则关闭处理。从源码看若指定的 handler key 未注册构造时会直接抛错The specified test handler ... is not defined因此这里的值必须与 handlers 注册表中的 key 严格一致。Development 模式与测试模式类似当NODE_ENV不是production时自动进入开发模式默认判定条件为process.env.NODE_ENV ! production见 mailer.ts。开发模式行为与测试模式相似默认尝试使用redwoodjs/mailer-handler-studio包。手动配置方式development: { when: process.env.NODE_ENV ! production, handler: someOtherHandler, },:::tip 开发模式下推荐配合 Mailer Studio 使用它提供一个本地邮件收件箱让邮件发送到本地机器即可查看结果同时提供渲染模板的实时预览作为最终用户看到的样式的参考。 :::Production 模式当 test 与 development 的判定条件均不满足时即NODE_ENV production且未自定义when进入生产模式。此模式下不会对邮件做任何重路由邮件直接交给默认 handlerhandling.default投递除非在send的发送选项中显式指定handler。用测试模式验证邮件in-memory 收件箱实战测试模式最大的价值在于可以放心断言邮件内容。沿用上面的联系表单示例在api/src/services/contacts/contacts.test.ts中编写如下测试见 mailer.mddescribe(contacts, () { scenario(creates a contact, async () { const result await createContact({ input: { name: String, email: String, message: String }, }) expect(result.name).toEqual(String) expect(result.email).toEqual(String) expect(result.message).toEqual(String) // Mail const testHandler mailer.getTestHandler() as InMemoryMailHandler expect(testHandler.inbox.length).toBe(1) const sentMail testHandler.inbox[0] expect({ ...sentMail, htmlContent: undefined, textContent: undefined, }).toMatchInlineSnapshot( { attachments: [], bcc: [], cc: [], from: contact-usexample.com, handler: nodemailer, handlerOptions: undefined, headers: {}, htmlContent: undefined, renderer: reactEmail, rendererOptions: {}, replyTo: String, subject: New Contact Us Submission, textContent: undefined, to: [ inboxexample.com, ], } ) expect(sentMail.htmlContent).toMatchSnapshot() expect(sentMail.textContent).toMatchSnapshot() }) })测试的核心抓手是mailer.getTestHandler()它返回当前测试 handler源码见 mailer.ts优先返回test.handler配置的实例否则返回自动加载的 fallback 实例。InMemoryMailHandler 的inbox数组源码见 in-memory handler记录了每一封被「发送」的邮件包含完整发送选项to、cc、bcc、from、replyTo、subject、headers、attachments渲染后的textContent与htmlContent元信息handler、handlerOptions、renderer、rendererOptions来自MailUtilities。上面测试的断言逻辑可以拆成三点确实发了一封邮件testHandler.inbox.length为 1发送选项正确通过 inline snapshot 断言 to、from、replyTo、subject、handler、renderer 等字段与预期完全一致注意快照中replyTo为String这正是replyTo: input.email传入测试输入的结果渲染内容正确htmlContent与textContent分别匹配快照保证模板渲染的正文符合预期。利用InMemoryMailHandler.clearInbox()in-memory handler还可以在多个测试用例之间重置收件箱避免邮件互相污染。与 RedwoodJS Studio 集成RedwoodJS Studio 与 Mailer 深度集成目标是不仅提供发送能力还提供更顺畅的开发体验见 mailer.md。模板实时预览Studio 提供邮件模板预览功能模板会随代码改动实时重渲染并且可以传入一个 JSON payload 作为模板组件的 props。这些预览是近似效果但通常足以覆盖 90% 的样式核对需求。本地收件箱在开发模式下使用默认的redwoodjs/mailer-handler-studiohandler 时邮件会被发送到 Studio 内部运行的本地 SMTP 收件箱端口 4319。这意味着你可以在开发环境中跑通完整的邮件收发流程而不必自建本地收件箱也不必依赖在线临时收件箱服务。从源码看StudioMailHandler 内部就是封装了指向localhost:4319的 NodemailerHandlerstudio handler若本地 SMTP 不可用会打印引导提示「Sent an email to the void! You can view this email during development with Redwood Studio:yarn rw studio」。自定义 Renderer 或 Handler如果官方内置的 handler / renderer 无法满足你的服务或技术栈需求完全可以自行实现并开源回馈社区见 mailer.md。实现的关键是满足redwoodjs/mailer-core包中定义的接口自定义renderer继承AbstractMailRenderer实现render(template, options, utilities?)返回{ html, text }以及internal()返回内部状态自定义handler继承AbstractMailHandler实现send(renderedContent, sendOptions, handlerOptions?, utilities?)返回MailResult可含messageID与handlerInformation以及internal()。官方实现的 handlers 位于 packages/mailer/handlers、renderers 位于 packages/mailer/rendererscore 接口定义位于 packages/mailer/core都可以作为编写自定义实现的直接参考。小结RedwoodJS Mailer 通过 renderer/handler 的两层抽象把「邮件内容生产」与「邮件投递」彻底分离让你可以在任意 Service 中一行式发送模板邮件按单封邮件指定 Resend、SES 或 Nodemailer在测试模式用 in-memory 收件箱做精确断言在开发模式借助 Studio 本地收件箱与实时模板预览完成调试在生产模式直连默认投递渠道。这套设计把邮件从「发出去就完事」提升为可设计、可预览、可测试的完整工程能力。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐RedwoodJS Mailer 完全指南端到端的邮件发送、渲染、测试与 Studio 集成RedwoodJS Mailer 完全指南端到端的邮件发送、渲染、测试与 Studio 集成 导读 RedwoodJS Mailer 是 RedwoodJS后端前端Web框架开发工具Jinja 沙箱Sandbox完全指南用 SandboxedEnvironment 安全渲染不可信模板Jinja 沙箱Sandbox完全指南用 SandboxedEnvironment 安全渲染不可信模板 本指南以 Jinja 官方文档 docs/sand后端RedwoodJS渲染器模板渲染与页面生成的终极指南RedwoodJS渲染器模板渲染与页面生成的终极指南 RedwoodJS是一个基于React和GraphQL的全栈JavaScript框架提供了强大的模板渲后端前端Web框架开发工具上一篇SpacetimeDB 浏览器快速入门用内联 JavaScript 构建实时 Web 应用下一篇恶意 npm 包检测的威胁建模与标准映射Anthropic-Cybersecurity-Skills 中 detecting-malicious-npm-packages 技能实战解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考