1. 为什么在Node.js项目里发邮件我最终选了Nodemailer先交代一个背景我先是用Node.js原生能力去摸SMTP协议打算自己封装一个简单的邮件发送模块。折腾了两天终于能发出第一封邮件但随之而来的是超时重试、附件编码、中文标题乱码、TLS握手异常、邮件被收件方扔进垃圾箱……一整套烂摊子。后来切换到Nodemailer之前那些问题大部分都消失了。Nodemailer本身不复杂但真正用好它需要理解transport、mail message、连接池、身份认证机制这些概念而不只是照抄文档。Nodemailer在Node.js生态里几乎是“发送电子邮件的标准答案”。你可以不引入它自己用smtp-client甚至裸写net模块与SMTP服务器对话但接入鉴权、TLS、MIME编码、附件处理这类脏活累活自己做一遍的成本非常高。我的建议是除非你只是为了学习SMTP协议否则直接站在Nodemailer肩膀上。它支持普通文本、HTML、内嵌图片、附件、批量发送、连接池、异步队列回调随便一个功能拿出来都可以单独讲一篇。这篇博客不是翻译官方文档而是把我在实际项目中踩过的坑、用过的写法、验证过的思路整理出来。适合三种读者第一次在Node.js里做邮件通知的初学者想改进现有邮件模块可维护性的开发者以及对“为什么这样配置”有好奇心的人。2. 安装与环境准备先把“从哪发、发给谁”这件事想清楚2.1 安装Nodemailer与Node.js版本要求在项目根目录执行npm install nodemailer如果你用的是pnpm或yarn命令大同小异pnpm add nodemailer yarn add nodemailer安装完之后建议先确认一下Node.js版本。Nodemailer当前主流版本要求Node.js 14以上但我个人建议直接在Node.js 20环境里跑因为新版对TLS、异步错误处理、ESM生态的支持都更省心。如果你的项目还在Node.js 12左右的老环境可能会有一些加密算法上的兼容问题比如TLS握手失败这类问题后面会专门谈到。2.2 CommonJS和ESM两种引入方式Nodemailer的历史包袱不算重CommonJS和ESM两种写法都支持。CommonJS项目里大多数人这么写const nodemailer require(nodemailer);如果你是ESM项目import nodemailer from nodemailer;除非你全项目统一了ESM风格否则我建议跟着项目现有风格走。这里有一个很容易忽略的点如果你在ESM项目里用了import nodemailer from nodemailer实际上拿到的是默认导出对象功能上没有区别但如果你的构建工具开启了esModuleInterop之外的严格风格偶尔会遇到“default is not a function”之类的报错。这时可以改成import * as nodemailer from nodemailer;或者退回CommonJS的require写法每个人项目情况不一样遇到报错时逐层排查即可。2.3 SMTP服务商的选择与授权码发邮件必须有发送方的SMTP账号。这个账号可以是企业邮箱的SMTP、云服务商提供的SMTP、某个免费邮箱提供的SMTP。我的建议是如果你的项目是给公司业务用的优先用公司域名的企业邮箱SMTP或云服务商邮件服务而不是拿某个个人免费邮箱去发业务通知。原因倒不是技术上的免费邮箱对日发送量限制很严格可能从某天开始你的批量通知就被静默丢弃了排查起来非常痛苦。配置SMTP时现在主流邮箱服务基本都不允许用账号的登录密码直接做SMTP认证而是要求单独生成一个“授权码”。这个授权码相当于SMTP认证专用的、权限受限的密码。不同服务商对授权码的生成位置和规则差异很大有的按客户端类型生成有的则是独立的字符串。配置之前先去邮箱设置里找到SMTP服务的授权码开关。用授权码当pass而不是登录密码这是我见过最多新手的第一个坑。2.4 准备SMTP配置清单在写代码前我建议先把下面几个字段整理出来后面创建transport时直接填字段含义示例hostSMTP服务器地址smtp.example.comportSMTP端口465 或 587secure是否使用SSL/TLS直接连接465通常为true587通常为falseuser发送账号nikeexample.compass授权码16位随机字符串这里有一个通用经验端口465一般走的是隐式SSL即从一开始就建立TLS加密通道端口587走的是STARTTLS即先在明文连接上协商升级到加密通道。大多数现代SMTP服务两个端口都兼容但如果某种组合反复报“无法验证服务器证书”之类的错换一下secure配置可能就好了。3. 第一个能跑通的Demo创建Transport、发送最简单的邮件3.1 一个最小化的发送脚本我尽量让第一个示例没有任何多余的包装先确认链路通不通const nodemailer require(nodemailer); async function main() { // 1. 创建transport const transporter nodemailer.createTransport({ host: smtp.example.com, port: 465, secure: true, auth: { user: noreplyexample.com, pass: 你的授权码, }, }); // 2. 构造邮件信息 const info await transporter.sendMail({ from: noreplyexample.com, to: someoneexample.com, subject: 测试邮件, text: 这是一封来自Node.js的测试邮件, }); console.log(邮件已发送消息ID, info.messageId); } main().catch(console.error);这段代码虽然短但它把Nodemailer最核心的用法完整展示出来了nodemailer.createTransport()创建发送通道transporter.sendMail()发送邮件。注意sendMail()返回的是一个Promise虽然你传回调也能用所以用async/await去接是最自然的。3.2 createTransport参数解读host、port、secure三者的关系新手最容易迷糊的就是secure这个布尔值。我用一句话说明secure: true表示“我连接SMTP服务器时从一开始就使用TLS加密”secure: false表示“我先用普通TCP连接到服务器然后按需升级到TLS”也就是STARTTLS模式。不要把secure理解为“是否加密发送”它实际上决定的是“加密握手发生在什么时候”。拿最常用的端口组合来说使用port: 465时通常配secure: true。使用port: 587时通常配secure: false并要求服务器支持STARTTLS。如果配错组合常见的报错会是Error: self signed certificate或者Error: Connection closed unexpectedly遇到这种报错第一步不是去查证书而是确认端口和secure是否匹配。我自己的经验是绝大多数免费和企业邮箱服务都能通过465直接跑通所以初学阶段用465 secure: true最省事。3.3 sendMail返回的对象到底有什么用sendMail返回一个SentMessageInfo对象实际用下来最常用的是这几个属性messageId消息的唯一ID格式类似xxxexample.com用于日志记录和追溯。accepted服务器明确接受的收件人数组。rejected被拒绝的收件人数组。responseSMTP服务器返回的原始响应文本。生产环境里我一般会把accepted、rejected都打出来。尤其是批量发送时某些收件人地址因为不存在或被服务商拦截sendMail并不会直接抛异常而是进入rejected数组。如果你只检查catch会漏掉大量实际没送达的数据。4. 邮件内容结构的细节from、to、subject、text/html的正确姿态4.1 from字段的“显示名”与地址分离最基础的用法是把from写成纯邮箱地址from: noreplyexample.com但如果你希望收件人看到一封“某某系统通知”而不是一个光秃秃的邮箱地址就应该写成对象或带显示名的字符串from: { name: 订单通知中心, address: noreplyexample.com, }或者简写from: 订单通知中心 noreplyexample.com这里有一个中文显示名编码的坑有些人直接写from: 订单通知中心 noreplyexample.com结果发现收件箱里显示名乱码。Nodemailer在编码非ASCII显示名时理论上会自动做RFC2047编码但为了兼容各种老式邮件客户端最好还是用对象写法别用混合字符串。我实际测下来对象写法在Outlook、各种主流邮箱App上的兼容性最稳。4.2 to、cc、bcc与多收件人to不仅支持单地址也支持数组to: [user1example.com, user2example.com]cc和bcc同样如此。一个容易忽略的问题是如果收件人特别多一封邮件带几十个to地址有些SMTP网关会触发“疑似垃圾邮件”风控。如果你要一次发送大量不同内容的邮件不要把它们全塞进一个to数组而应该用循环或队列逐封发送后面会专门讲。4.3 text与html同时存在的意义业务邮件里经常只写html却忘了text。其实这两个字段同时提供是最稳妥的const mailOptions { from: noreplyexample.com, to: userexample.com, subject: 周报提醒, text: 这是纯文本版本, html: p这是strongHTML/strong版本/p, };原因很简单部分严谨的安全网关会禁用邮件中的HTML渲染或者收件人客户端默认只显示纯文本。如果没有text字段他们看到的会是一堆原始HTML标签。哪怕你的业务主要靠HTML展示也顺手写一个纯文本摘要成本极低但送达后体验完全不同。4.4 自定义Headers与回复地址有些场景需要设置Reply-To比如通知邮件希望收件人直接回复到客服邮箱replyTo: supportexample.com,也可以加自定义头headers: { X-Priority: 1, X-Mailer: MyApp-Mailer/1.0, }自定义头在做退订、标记优先级、内部分类时很好用。但注意别随意篡改Message-ID、Date这类由SMTP服务器负责的标准头改坏了反而容易被拒收。5. 进阶场景一HTML模板、内嵌图片与附件处理5.1 用模板字符串组织HTML邮件最简单的HTML邮件可以直接拼字符串但如果内容一长拼查询参数和循环数据就变得很痛苦。我常用的做法是用模板字符串加一个简单渲染函数function renderOrderEmail(order) { return div stylefont-family: Arial, sans-serif; h2订单确认通知/h2 p亲爱的 ${order.customerName}/p p您的订单已确认订单号${order.orderNo}/p table border1 cellpadding6 cellspacing0 trth商品/thth数量/thth价格/th/tr ${order.items.map((item) tr td${item.name}/td td${item.quantity}/td td${item.price}/td /tr ).join()} /table p合计${order.total}/p /div ; }如果邮件模板更多、更复杂我建议引入模板引擎比如ejs或handlebars把纯展示逻辑和业务逻辑分开。用ejs渲染一个文件模板通常是const ejs require(ejs); const html ejs.render(fs.readFileSync(views/order.ejs, utf-8), { order });这一步不是在增加项目复杂度而是让后续改邮件样式的人不用去Node逻辑里翻字符串拼接。5.2 内嵌图片与外部图片的区别邮件里放图片有两种方式第一种是把图片放到外网URL上直接在img srchttps://...引用。这种方式简单但很多邮件客户端默认阻止加载外链图片收件人看到的是空白占位符。第二种是CID内嵌即把图片作为附件附带在邮件里并通过cid引用const mailOptions { to: userexample.com, subject: 带内嵌图的活动通知, html: p欢迎参加活动/pimg srccid:event_banner/, attachments: [ { filename: banner.png, path: /path/to/banner.png, cid: event_banner, }, ], };注意cid值要跟srccid:...里的名字完全一致。内嵌图片的优点是收件人打开邮件时图片立即显示不依赖外部网络缺点是邮件体积变大。我的经验是一条横幅、一两张关键图适合用CID大量商品图还是外链更合适。5.3 attachments的多种content来源Nodemailer附件最灵活的地方在于content可以来自多种来源文件路径{ filename: report.pdf, path: /tmp/report.pdf }Buffer给数据库里的二进制数据直接当附件用Stream适合超大文件流式发送URL{ filename: logo.png, path: https://example.com/logo.png }一个常用的例子是把生成的PDF作为附件const pdfBuffer await generatePdf(order); const mailOptions { to: order.email, subject: 您的电子发票, html: p发票见附件/p, attachments: [ { filename: invoice-${order.orderNo}.pdf, content: pdfBuffer, contentType: application/pdf, }, ], };这里要说一个容易踩的坑当你用URL作为附件路径时Nodemailer默认会去下载这个URL。如果URL指向的内网地址无法联通发送过程会等待很长时间然后失败。这时候不如先把文件下载成Buffer再传给content至少你能自己控制超时。6. 进阶场景二批量发送、连接池与失败重试6.1 循环发送时的“复用transport”原则很多人第一次写批量通知会写出类似这样的代码for (const user of users) { const transporter nodemailer.createTransport(config); await transporter.sendMail({ ... }); }这样做最大的问题是效率极低每发一封邮件都要重新建立一次SMTP连接经历TCP握手、TLS握手、SMTP鉴权一封邮件的时间大部分耗在连接上。正确做法是复用一个transportconst transporter nodemailer.createTransport(config); for (const user of users) { try { await transporter.sendMail({ to: user.email, ... }); } catch (err) { console.error(发送失败${user.email}, err.message); } } await transporter.close();复用transport时Nodemailer默认会为每次sendMail维护连接队列确保同时只有限定数量的邮件在传输通道上。这个机制对绝大多数场景都够用。6.2 pool连接池参数调优如果你需要更高吞吐量可以在createTransport时开启连接池const transporter nodemailer.createTransport({ host: smtp.example.com, port: 465, secure: true, pool: true, maxConnections: 5, maxMessages: 100, auth: { user: noreplyexample.com, pass: your-code }, });参数含义pool: true启用连接池。maxConnections最多同时保持的连接数默认是5。maxMessages单个连接最多发送多少封邮件后重新连接默认是100。为什么需要maxMessagesSMTP服务器一般在连接上会有发送数量限制尤其是不允许一个连接无限收发。超过这个数量后重新建连能避免被服务器判定为异常行为。我的经验是默认值基本够用但如果你发现发送速率不达标优先加maxConnections再观察收件方是否有拒信。6.3 简单的重试策略网络不可能永远稳定。发送失败时直接丢弃还是重试需要根据业务决定。我项目里通常用一个带指数退避的重试函数async function sendWithRetry(sendFn, maxRetries 3) { let lastError; for (let attempt 1; attempt maxRetries; attempt) { try { return await sendFn(); } catch (err) { lastError err; const delayMs Math.pow(2, attempt) * 500; console.warn(第 ${attempt} 次发送失败${delayMs}ms 后重试, err.message); await new Promise((resolve) setTimeout(resolve, delayMs)); } } throw lastError; }业务里可以这样调用for (const user of users) { await sendWithRetry(() transporter.sendMail({ to: user.email, subject: 批量通知, text: 内容, })); }注意重试要避开两个陷阱第一不要所有收件人同时重试否则某个SMTP抖动会导致瞬时流量翻几倍第二sendMail本身如果已经成功到达服务器只是响应超时重试会造成同一封邮件被发两次。这种场景需要你记录messageId或业务唯一标记做幂等处理不过那是另一个复杂话题这里先提醒一下。7. 本地开发调试用测试信箱和全量日志定位问题7.1 为什么要用测试SMTP服务在开发阶段如果你直接拿公司或个人的真实邮箱发测试邮件不仅污染真实收件箱还可能因为发送频率过高触发风控。Nodemailer文档推荐了一个特别好用的测试服务可以临时生成一个虚拟SMTP账号收到的邮件会存在一个Web页面上方便查看渲染效果和原始MIME结构。使用起来大概是这样的思路以下为可运行的示例代码const nodemailer require(nodemailer); async function createTestTransporter() { const testAccount await nodemailer.createTestAccount(); const transporter nodemailer.createTransport({ host: testAccount.smtp.host, port: testAccount.smtp.port, secure: testAccount.smtp.secure, auth: { user: testAccount.user, pass: testAccount.pass, }, }); return { transporter, testAccount }; }createTestAccount()会返回一组临时的SMTP配置。用这组配置创建transport后你发出去的邮件不会寄到现实中的邮箱而是出现在测试信箱的网页里。sendMail返回的info对象中会带一个预览URL直接把那个URL发给别人对方也能看到这封邮件的HTML渲染效果。这是本地开发调试的“救命稻草”不用配置真账号、不用等邮件送达、不担心发错人而且能同时看到纯文本版、HTML版、附件列表、原始邮件头比你在真实邮箱里看得还清楚。7.2 开启debug和logger看原始SMTP会话有些问题只靠报错信息根本看不出原因比如服务器返回了奇怪的错误码、认证格式不对、TLS握手证书信息有偏差。这时候就需要开启调试日志const transporter nodemailer.createTransport({ host: smtp.example.com, port: 465, secure: true, auth: { user: noreplyexample.com, pass: your-code }, debug: true, logger: true, });debug: true会把你和SMTP服务器之间的原始会话打印出来能看到每一次EHLO、AUTH LOGIN、MAIL FROM、RCPT TO、DATA指令的交互。而logger: true则让Nodemailer内部用统一的日志器输出更结构化的信息。一个特别经典的场景是你发现某封邮件发不出去日志里出现553 sorry, your envelope sender is rejected这通常意味着你冒用了某个域名的发件地址但SMTP服务器不允许该域名从你这个IP发出。这种问题不开日志是永远猜不到的。记得生产环境要把debug关掉否则邮件内容和SMTP认证信息可能全部打进日志有泄露风险。7.3 transport的关闭时机另一个高频小问题脚本跑完后直接退出结果邮件没发出去。这是因为Nodemailer的transport是异步工作的如果你用短脚本测试可能进程已经退出但SMTP连接还有未完成的数据交换。正确的做法是在所有发送任务结束后显式关闭transportawait transporter.close();如果你在Web服务里使用Nodemailer通常不需要频繁关闭因为transport在进程生命周期内复用即可。但如果你写的是一次性定时脚本、CI任务、命令行工具一定要在结尾close()否则日志里会出现“邮件显示发送成功但实际没有送达”的诡异现象。8. 异常排查链路从报错信息到根因定位的完整思考方式8.1 常见报错与对应排查步骤我把自己经历过的、也帮别人排查过的几类问题整理成一个对照表报错或现象常见根因第一步排查动作Invalid login: 535 authentication failed授权码错误或账号前缀写错去邮箱后台重新生成授权码确认user是否带域名后缀self signed certificatesecure参数与端口不匹配或服务器证书链异常先检查465配true、587配false再确认是否为内网SMTP自签证书connect ECONNREFUSED端口未开放、服务器地址写错telnet smtp.example.com 465看端口通不通Timeout while connecting to SMTP server本地网络出网受限、SMTP端口被防火墙拦截换网络环境测试用netstat或nc -zv检查连通性发送成功但收件人一直收不到被网关判定垃圾邮件、SPF/DKIM缺失检查发送域名SPF/DKIM记录查看原始邮件头的Received链路中文标题乱码未启用正确编码或某些客户端兼容性问题尽量用对象形式的from给subject显式加charset相关配置8.2 排查“发送成功但用户收不到”的完整链路这是最让人抓狂的问题因为发送方完全没有任何异常。我的排查思路是分四步走第一步检查sendMail返回的accepted是否包含该收件人。如果包含说明你的SMTP服务器端接受了这封邮件如果不包含说明在入口就被拒绝了。第二步打开原始邮件头很多邮箱客户端提供“显示原始邮件”功能看Received链路上是否有“你的服务器 - 收件方服务器”的记录。如果只有发送方记录说明邮件还在路上或已在中间环节被丢弃。第三步检查发件域名配置。大多数垃圾邮件过滤系统会校验发件域名的SPF记录和DKIM签名。如果域名没有配置SPF或者服务器IP不在SPF允许列表里收件方网关很容易直接拒收。第四步检查邮件内容是否触发内容风控。比如大量使用外链、包含明显营销词、HTML里没有纯文本替代这些都会提高被分类为垃圾邮件的概率。一个稳妥的做法是先用测试SMTP看渲染再用真实小范围名单发一次确认落地正常。8.3 证书与TLS问题的专项说明如果你在公司内网自建SMTP服务器经常遇到自签名证书报错。有些人的第一反应是关闭证书校验tls: { rejectUnauthorized: false, }这个姿势虽然能让代码跑起来但等于放弃了TLS的安全意义。我的建议是如果是自建服务器把自签证书添加到系统信任库或配置Nodemailer的tls.ca指向正确的CA文件。这样既能保证加密通信又不用关闭证书校验tls: { ca: [fs.readFileSync(/path/to/server-ca.pem)], }如果你只是为了快速验证代码逻辑临时用rejectUnauthorized: false也能理解但上线之前一定要改回来。9. 生产环境实操经验我把哪些配置写进了项目模板聊了这么多基础用法和坑最后分享几个我在生产项目里一直坚持的配置习惯。第一个习惯是所有SMTP配置全部从环境变量读取不走配置文件写死。邮件发送涉及敏感信息一旦配置文件被提交到代码仓库等于把授权码暴露给了所有有仓库访问权的人。我一般在项目里用一个config模块统一读取const config { host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT || 465), secure: process.env.SMTP_SECURE true, auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS, }, };第二个习惯是统一封装一个mailer.js模块项目里其他地方不直接createTransport而是调用sendMail(to, subject, html, attachments)。这样将来如果要换队列、加日志、做失败重试改动只集中在同一个文件里。第三个习惯是邮件发送记录一定要有日志而且日志里要同时包含to、subject、messageId、发送结果四要素。排查线上问题时哪怕只是“某用户没收到邮件”这种小问题有完整日志也能省下大把时间。说实话Nodemailer本身不复杂复杂的是邮件系统的各种外部环境DNS配置、TLS证书、网关风控、编码兼容。把这些环境变量理解透了无论是发通知、发报表还是发营销邮件剩下的就是反复调参和经验积累。希望这篇内容能帮你少走一段弯路。