Nodemailer邮件发送实战：从SMTP配置到生产环境避坑指南

相信不少朋友在做 Node.js 项目时都碰到过这个需求用户注册后要发验证邮件、订单支付成功后要补一封通知邮件、后台系统每周要推一份数据报表。这事说大不大但真轮到自己从零接入还是有不少坑要踩的。我自己最早做邮件功能时直接在项目里拼net.Socket手写 SMTP 协议折腾到半夜才勉强把邮件发出去后来换了 Nodemailer才真正体会到什么叫“十分钟搞定邮件发送”。Nodemailer 是 Node.js 生态里最成熟、使用最广泛的邮件发送库底层封装了 SMTP 的完整通讯细节也支持 AMAZON SES、SendGrid 这类 HTTP API 服务。对绝大多数 Node.js 项目来说只要走 SMTP 发信选它就够了。我这个教程会从零开始带你完整走一遍“装环境、配置 SMTP、发文本邮件、发 HTML 模板邮件、加附件、排查问题”的全流程还会聊一些文档里不会写的实战细节比如为什么用授权码而不是登录密码、secure: true到底什么时候该开、线上环境如何避免 SMTP 连接数被打满等。无论你是刚接触 Node.js 的新手还是在公司里负责业务系统开发的工程师只要想快速、稳妥地把邮件发送能力集成进自己的项目这篇文章就能派上用场。1. 内容整体设计与思路拆解1.1 邮件系统为什么用 Nodemailer 而不是自己造轮子很多人第一次接触邮件发送。第一反应是不就是把邮件内容交给某个服务商吗好像很简单的样子。但真要自己上手实现的时候你会发现自己撞上的是一堵高墙——SMTP 协议要处理多条命令交互EHLO、MAIL FROM、RCPT TO、DATA、QUIT要处理认证流程AUTH LOGIN、AUTH PLAIN还要应对各种错误码和超时重试。即便你只用最基础的方式把邮件发出去中间涉及的编码问题标题用 Base64、正文用 quoted-printable、MIME 结构解析、附件分段等每一条都能消耗掉你半天时间。Nodemailer 的价值就是把这一整套流程封装成几行 API。你只需要在会上配置好 SMTP 服务器信息调用sendMail把“收件人、主题、正文”丢给它剩下的握手、认证、编码、发送、释放连接等操作全部由库内部完成。我在实际项目中对比过好几款 Node.js 邮件库最后长期保留的只有 Nodemailer。原因很简单它支持回执、抄送、密送、附件、嵌入图片支持流式附件比如直接从数据库读出来的 Buffer还内置了连接池管理机制。这些能力不是在“普通业务系统”里立刻就能派上用场的但当你开始做高并发通知、或需要批量推送系统告警时就会意识到一个可维护的邮件库比自定义脚本省心得多。1.2 当前主流邮件发送方案的选型对比说到底Node.js 项目里发邮件无非三条路官方 SMTP 直发、HTTP API 邮件服务、第三方邮件网关转发。我用一个表把它们的差异整理清楚了方案优点缺点适用场景Nodemailer SMTP通用性强几乎有邮箱就有 SMTP代码简单免费需要小心配置反垃圾邮件策略某些邮箱厂商限流严格中小项目、内网系统、公司自有域邮箱邮件 HTTP API如 AWS SES高可用、高送达率自带统计和退信反馈需要注册云厂商账号按量计费调用方式依赖厂商 SDK线上大规模通知、营销邮件、需要监测送达情况企业微信/钉钉邮箱转发国内可达性好往往免额外费用定制化程度低受限于企业邮箱体系内部办公自动化通知、告警消息推送如果你的项目跑在国内云服务器上并且收件人也是国内邮箱直接用 SMTP 直发通常就够了。如果收件人覆盖面广、送达率要求高建议把 Nodemailer 作为发送入口底层再接入 SES 这类接口代码层面只需要替换 transport 配置即可。1.3 理解邮件发送链路才能少踩坑要真正会用 Nodemailer不能只学 API还得对“一封邮件从发送到送达”的整个链路有基本概念。从你的 Node.js 进程发出邮件后实际路径是这样的Nodemailer 与 SMTP 服务器发件方的邮箱服务商建立 TCP 连接。通过 SMTP 协议完成握手和身份认证。将邮件内容信封 头 正文 附件推送给发件服务器。发件服务器收到后会与收件方邮箱服务器的 MX 记录对应的服务器进行后续投递。收件方服务器进行垃圾邮件过滤、反病毒扫描最后投递到收件人的收件箱或垃圾箱。理解这条链路后你就知道“发送成功”并不等于“对方一定在收件箱里看到了”。你的代码层面报错只代表“发件服务器接收成功”至于后续投递、被反垃圾策略拦截Nodemailer 是控制不了的。做好这个预期管理做系统设计时才不会犯“把送达率问题误判成代码问题”的低级错误。2. 环境准备与项目初始化2.1 Node.js 环境安装策略在动手写代码前得先把 Node.js 环境准备好。我假设你的系统是 Ubuntu 20.04 或 22.04这是目前国内云服务器最常见的环境组合。如果你用的 Windows思路其实一样只是安装命令略有差异。Ubuntu 下装 Node.js 20 有两条主流路径第一条是用 NodeSource 提供的二进制仓库# 更新 apt 源并安装 curl sudo apt update sudo apt install -y curl # 添加 NodeSource 仓库并安装 Node.js 20 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 查看版本 node -v npm -v第二条是我个人更推荐的方式用 nvm 管理 Node.js 版本。好处是你可以随时切换多个 Node 版本避免某天为了兼容老项目又被迫回滚系统的 Node。命令如下curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 环境 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh # 安装最新的 LTS 版本 nvm install --lts nvm use --lts用 nvm 安装时不需要sudo也不会污染系统全局环境非常适合长期做项目开发的场景。我自己的机器上就同时保留着 Node 18 和 Node 20切换到哪个项目就切到哪个版本的 Node。2.2 初始化项目并安装 Nodemailer环境就绪后先创建项目目录并执行npm initmkdir nodemailer-demo cd nodemailer-demo npm init -y接着安装 Nodemailernpm install nodemailer如果你用的是 npm 5 以后的版本npm install会自动把依赖写入package.json的dependencies字段同时生成package-lock.json之后在 CI 或新机器上跑npm install就会使用相同版本的依赖避免“我本地能跑线上跑不了”的尴尬。2.3 快速验证安装是否成功安装完成后可以在项目里写一个临时文件验证模块是否成功加载const nodemailer require(nodemailer); console.log(Nodemailer 版本:, nodemailer.version);然后在终端执行node testMailer.js能正常打印版本号说明模块安装到位了。这一步虽然简单但能提前排除一些莫名其妙的模块解析问题尤其是当你用了 pnpm 或 yarn 这类非默认包管理器时常见报错是Cannot find module nodemailer这时候先检查一下你的NODE_PATH环境变量。3. 核心原理拆解SMTP transport 配置与授权码机制3.1 transport 对象是什么Nodemailer 里最核心的两个概念transporter运输器和message邮件消息。你可以把transporter理解为“邮局门口负责送信的那个人”它知道怎么连接 SMTP 服务器、怎么认证身份、怎么把邮件交到服务器手里。而message就是信封里的信纸和包裹内容。创建一个 transporter 的代码看起来是这样const nodemailer require(nodemailer); const transporter nodemailer.createTransport({ host: smtp.qq.com, port: 465, secure: true, auth: { user: 你的邮箱地址qq.com, pass: 授权码 } });很多新手看完这段代码会疑惑auth.pass为什么不让填邮箱的登录密码而是填授权码这背后的设计逻辑其实很简单如果客户端登录密码一旦客户端代码或配置泄露攻击者就能直接登录你的邮箱账号后果不堪设想。而授权码相当于一把“专用钥匙”只能用于 SMTP 发信不能用来登录网页版邮箱、不能修改密码、不能删除邮件。万一授权码泄露你随时可以在邮箱设置里吊销它并重新生成主密码的安全性完全不会受影响。国内主流邮箱服务商如 QQ 邮箱、163 邮箱、126 邮箱、新浪邮箱基本都支持开启 SMTP 服务并生成授权码。以 QQ 邮箱举例你需要登录网页版邮箱进入“设置 → 账号”找到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”一栏开启“SMTP服务”按提示用手机发一条验证短信之后系统会给你一串十六位授权码。这串授权码就是pass字段要填的内容。有一点要提醒某些邮箱默认关闭 SMTP 服务。如果你用自己公司内部的企业邮箱往往需要找管理员开通。如果公司使用 Office 365 或 Exchange 在线版SMTP 地址通常是smtp.office365.com端口587这种情况下认证方式可能是 OAuth 2.0那就不是简单填授权码能解决的了。我的建议是小团队、快速上线阶段先用账号密码或授权码方式跑通等企业邮箱策略收紧后再升级认证。3.2 secure 与 port 的搭配细节secure字段可能是 Nodemailer 配置里最容易让人摸不着头脑的。我直接给你结论secure: true表示使用 SSL/TLS 加密连接对应的端口通常是465。secure: false表示使用非加密方式连接但支持在连接后通过STARTTLS升级为加密链接常用端口是587或25。这里不需要死记硬背理解一下就好端口 465从一开始就建立 SSL 加密隧道这也是 QQ 邮箱、163 邮箱默认推荐的端口。端口 587先以普通连接握手再通过 STARTTLS 命令升级为加密链接。这个端口在部分企业邮局和国外邮件服务中更常见。如果你写的是port: 465, secure: false很多邮箱服务器会直接拒连或者握手失败。一个务实的做法是先用邮箱服务商提供的默认配置模板跑通后再按需调整。以 QQ 邮箱官方文档为例smtp.qq.com:465配secure: true几乎是唯一指定方案。3.3 使用环境变量管理敏感配置我见过不少同事把邮箱账号和密码直接硬编码在代码里提交到 Git 仓库然后在真实线上出问题时才发现成了事故源头。更好的做法是把敏感配置放在环境变量或.env文件中。在项目里安装dotenv然后创建.envnpm install dotenv.env文件内容SMTP_HOSTsmtp.qq.com SMTP_PORT465 SMTP_USER你的邮箱qq.com SMTP_PASS你的授权码然后在入口文件顶部引入 dotenvrequire(dotenv).config(); const transporter nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT), secure: true, auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } });同时记得把.env加入.gitignore避免误提交。4. 实操过程从发送第一封文本邮件到完整 HTML 邮件4.1 发送第一封文本邮件环境配好后写一个最简单不过的发送脚本const nodemailer require(nodemailer); require(dotenv).config(); async function sendTextMail() { const transporter nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT), secure: true, auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } }); const mailOptions { from: 系统通知 ${process.env.SMTP_USER}, to: 收件人1example.com, 收件人2example.com, subject: 这是一封测试邮件, text: 你好这是一封来自 Nodemailer 的测试邮件。 }; try { const info await transporter.sendMail(mailOptions); console.log(邮件发送成功:, info.messageId); console.log(预览地址:, nodemailer.getTestMessageUrl(info)); } catch (error) { console.error(发送失败:, error); } } sendTextMail();跑一下脚本node sendTextMail.js成功的话控制台会打印出类似这样的信息邮件发送成功: 20231001092345.123456qq.commessageId是由发件服务器生成的唯一标识后面排查邮件问题时比如给客服工单提交邮件 ID会用到。nodemailer.getTestMessageUrl(info)这个方法只在使用了nodemailer.createTestAccount()创建的测试账户时才会返回预览地址生产环境用真实 SMTP 发送时返回的是false。别在真实邮件场景里期待看到预览链接这是一个常见误解。4.2 使用 HTML 模板替代纯文本现如今的业务邮件很少只发纯文本。优惠券发放、订单确认、注册验证几乎都是漂亮的 HTML 页面模板。Nodemailer 支持直接在mailOptions里传html字段它会自动生成 MIME 类型的text/html内容。const mailOptions { from: XX商城 ${process.env.SMTP_USER}, to: customerexample.com, subject: 订单确认通知, html: div stylemax-width: 600px; margin: 0 auto; font-family: Arial, sans-serif; h2 stylecolor: #333;感谢您的订购/h2 p您的订单 strong#10086/strong 已支付成功正在加急处理中。/p table styleborder-collapse: collapse; width: 100%; margin-top: 20px; tr stylebackground: #f5f5f5; th stylepadding: 8px; text-align: left;商品名称/th th stylepadding: 8px; text-align: left;数量/th th stylepadding: 8px; text-align: left;金额/th /tr tr td stylepadding: 8px;无线机械键盘/td td stylepadding: 8px;1/td td stylepadding: 8px;¥399.00/td /tr /table /div };在实际工程里我更推荐把 HTML 模板拆成独立文件用模板引擎渲染动态数据。我常用的是ejs或者handlebars两者在 Node.js 生态里都非常成熟。举个例子用handlebarsnpm install handlebarsconst fs require(fs); const Handlebars require(handlebars); const source fs.readFileSync(templates/order-confirm.hbs, utf8); const template Handlebars.compile(source); const html template({ orderId: #10086, customerName: 张三, items: [ { name: 无线机械键盘, qty: 1, price: ¥399.00 }, { name: 鼠标垫, qty: 2, price: ¥49.00 } ] });再用渲染好的html传进sendMail。这样邮件内容和业务数据解耦后续调整样式也不会影响发送逻辑。4.3 添加附件和嵌入图片附件是邮件功能中避不开的重头戏。财务系统导出 Excel 报表、订单系统导出 PDF 发票、运维系统发日志压缩包都是在attachments字段里配置的。const mailOptions { from: 数据报表系统 ${process.env.SMTP_USER}, to: managerexample.com, subject: 10月运营数据日报, html: p请查收附件中的日报数据。/p, attachments: [ { filename: daily-report.xlsx, path: /tmp/daily-report.xlsx }, { filename: report.pdf, content: pdfBuffer, // Buffer 类型 contentType: application/pdf } ] };如果附件是运行时动态生成的比如调用 Excel 库生成的报表 Buffer没必要先写进磁盘直接通过content传给 Nodemailer 就行。它会做 Base64 编码并组装 MIME 结构效率更高。还有一种是嵌入正文的图片比如邮件底部带一个产品海报图。做法是设置cidattachments: [ { filename: banner.png, path: /path/to/banner.png, cid: banner_01 } ]然后在 HTML 里通过cid引用img srccid:banner_01 altbanner /这种方式比把图片传到外网再用 URL 引用要可靠得多不会出现“邮件内有图但对方网络加载不出来”的尴尬。4.4 多人发送收件人、抄送、密送Nodemailer 在多人发送方面做得很顺手。to、cc、bcc都支持逗号分隔的多个邮箱地址const mailOptions { from: 行政部 hrexample.com, to: zhangsanexample.com, lisiexample.com, cc: managerexample.com, bcc: logexample.com };需要留意的点是bcc收件人不会出现在任何其他收件人的邮件头中适合做“静默备份”。比如你给客户发一封重要通知同时想留底给公司邮箱就把留底地址放在bcc里客户不会看到备查邮箱的身影。如果你要遍历一个大的收件人列表逐封发送比如五千个用户逐封发送重置密码邮件我建议别用一次to塞太多地址。邮箱服务商普遍单封邮件收件人数有限制QQ 邮箱是单次最多 50 个左右Gmail 是 500 个左右具体数值跟账号等级有关。一旦超过限制整个请求会被 SMTP 服务器拒绝。更稳妥的做法是分批次发送每批 50 人以内并加一个小的延时。5. 生产环境实战连接池、重试机制、错误排查5.1 连接池配置避免并发打爆 SMTP 连接数很多人在本地测试邮件功能每天只发几封不会发现问题。但到了线上业务高峰期一下就涌来几千封通知邮件如果不加控制每封邮件都新建一个 SMTP 连接、用完后立刻断开邮件服务商那边会迅速触发频率限制甚至封禁你的 IP。Nodemailer 的解决方案是连接池。它会在createTransport阶段预创建一批 SMTP 连接发送完成后不会立刻断开而是重新放回池中供下次复用。const transporter nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT), secure: true, pool: true, maxConnections: 5, maxMessages: 100, rateDelta: 1000, rateLimit: 5, auth: { ... } });解释一下几个参数pool: true开启连接池模式。maxConnections最多同时维持的 SMTP 连接数我一般设 5具体看你的邮箱服务商限制。maxMessages一条连接最多发送多少封邮件后关闭重建。避免长时间使用同一条连接引发异常。rateLimit和rateDelta限流设置。rateLimit: 5, rateDelta: 1000表示每秒钟最多发出 5 封邮件。这个组合既能保证发送速度又不会把邮箱服务商惹毛。我自己做内部通知系统时用的就是这个配置高峰 5000 封邮件大概几分钟内就能排完几乎没有触发过限流。5.2 发送失败后的重试与补偿策略线上邮件发送是典型的“不可靠操作”网络抖动、SMTP 认证超时、收件方服务器拒绝任何一环出错你的业务代码都得有兜底方案。重试这件事不能无脑做。我的做法是发送前先把邮件数据序列化存储存 JSON 到数据库或消息队列。首次发送失败时记下失败原因。按指数退避策略重试比如 1 分钟、5 分钟、30 分钟各重试一次。超过最大重试次数后转人工处理或把邮件标记为failed。如果是高并发场景我还会引入消息队列。业务系统只需要把“发送任务”交给队列消费者从队列里拉任务、调 Nodemailer 发送、成功后确认消息。这种模式的好处是邮件量突增时队列帮你削峰邮件服务商限流时消费者后端自动降速。一个非常容易踩的坑是重试时把重复邮件发给用户。比如用户下了一个订单系统自动发确认邮件。第一次发送超时但服务器实际已接收你的代码捕获到了超时错误并触发重试结果用户收到了两封一模一样的邮件。解决思路是业务系统提前做幂等订单表里记录mail_sent_at字段重试前检查该字段是否已有值或者用一个独立的邮件发送记录表以orderId type做唯一索引。5.3 常见错误码排查速查表邮件发送报错信息五花八门但仔细观察会发现高频错误就那些。我把常见的错误整理成速查表错误现象可能原因排查方向EAUTH用户名或授权码错误检查邮箱地址是否完整、授权码是否过期尤其在修改邮箱密码后需重新生成授权码ECONNECTION连接 SMTP 服务器失败检查 host/port 是否正确Telnet 测试连通性telnet smtp.qq.com 465检查安全组和防火墙ETIMEDOUTSMTP 服务器响应超时多数是网络链路问题或对方服务器瘫痪重试一次或更换发件服务商EENVELOPE信封地址格式错误检查from、to字段是否附带合法邮箱地址不要写张三 xxx以外的格式EMESSAGE邮件内容格式问题检查 HTML 是否闭合、附件路径是否存在、文件名是否包含非法字符550收件人地址不存在或邮件被拒绝确认收件人地址拼写域名是否存在 MX 记录535认证失败大多也是授权码问题或发送频率过高触发风控421服务暂不可用高频发送被临时限制降低速率稍后补发排查时有一类问题容易忽略很多云服务器默认封禁了 25 端口。如果你配置的 SMTP 端口是 25会发现telnet连不通这通常不是你的程序问题而是云服务商主动屏蔽了 25 端口以防止垃圾邮件滥用。解决办法是改成 465 或 587。5.4 开启 debug 模式看完整 SMTP 对话当你实在排查不出问题时最原始的办法就是看 SMTP 的完整对话过程。Nodemailer 提供了debug和logger参数const transporter nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT), secure: true, auth: { ... }, debug: true, logger: true });debug: true会把 SMTP 客户端与服务器之间的原始通讯输出到控制台logger: true则输出 Nodemailer 自身更结构化的日志。看到完整交互流程后很多困惑会一瞬间解开。比如你能清楚看到服务器返回的535 Authentication failed或某个命令被服务器拒绝时的具体原因码。不过debug: true会打印授权信息相关的中间内容虽然不会直接打印密码明文但生产环境还是要谨慎建议只在测试环境开启排查完立刻关闭。6. 一个完整可复用的工具类封装6.1 封装邮件发送服务经过前面这么多环节最后把这些经验整合成一个可复用的邮件服务模块团队里的人拿来就能用。我习惯创建一个services/mailer.js文件导出几个方法const nodemailer require(nodemailer); require(dotenv).config(); let transporter null; function getTransporter() { if (!transporter) { transporter nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT), secure: Number(process.env.SMTP_PORT) 465, pool: true, maxConnections: 5, maxMessages: 100, rateLimit: 10, rateDelta: 1000, auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS } }); } return transporter; } async function sendMail({ to, subject, text, html, attachments, cc, bcc }) { const mailOptions { from: ${process.env.MAIL_FROM_NAME || 系统通知} ${process.env.SMTP_USER}, to, cc, bcc, subject, text, html, attachments }; const info await getTransporter().sendMail(mailOptions); return { messageId: info.messageId }; } module.exports { sendMail };使用时就非常清爽了const { sendMail } require(./services/mailer); await sendMail({ to: userexample.com, subject: 账户激活, html: p点击链接激活您的账户/p });这个封装有几个好处全局复用同一个 transporter避免每次请求都新建连接、统一处理环境变量、调用方不用关心 SMTP 细节。业务代码里只需要传递业务字段即可。6.2 结合定时任务发送报表最后分享一个小场景每周一早上 9 点定时给管理层发上周运营数据报表。我的做法是配合node-cron这样的调度库npm install node-cronconst cron require(node-cron); const { sendMail } require(./services/mailer); const { generateWeeklyReport } require(./services/report); cron.schedule(0 9 * * 1, async () { try { const { fileName, buffer } await generateWeeklyReport(); await sendMail({ to: managerexample.com, subject: 上周运营数据报表 ${new Date().toISOString().slice(0, 10)}, html: p上周的运营数据请见附件。/p, attachments: [ { filename: fileName, content: buffer } ] }); console.log(周报已发送); } catch (err) { console.error(周报发送失败:, err); } });这样一套下来运营团队再也不用每周手动跑数据、手动发邮件了。邮件服务的稳定性、排查链路、发送速率控制都在前面的轮子里已经解决。7. 常见问题与排查技巧实录7.1 我用测网易邮箱时踩过的“授权码”坑最早做测试时我用网易 163 邮箱做 SMTP 发件方。当时顺手在代码里填了邮箱的登录密码怎么试都报EAUTH查了半天才发现 163 邮箱同样需要先在网页端开启 SMTP 服务并生成专用授权码。后来我总结了一个规律凡是在设置里能看到 “SMTP 服务” 开关的邮箱几乎都要求使用授权码而不是登录密码。遇到EAUTH第一反应就是重新生成授权码并立刻测试。7.2 生产环境“发送成功但收不到”的排查顺序如果你确认 Nodemailer 中没有报错但用户始终收不到邮件可以按以下顺序排查先检查垃圾箱。很多高频通知邮件可能被误判进垃圾箱。检查发件方的域名解析。如果你用的是企业域名邮箱确认域名的 SPF 记录、DKIM 记录是否配置正确。缺失这些记录收件方邮箱大概率会提升垃圾邮件判定等级。检查收件人邮箱是否启用了“会话”分组有些邮件会默认收进“促销邮件”“社交邮件”分类里。用相同内容从同一个发件邮箱在网页端手动发送一封对比测试如果网页端能正常收到而程序发送收不到说明问题出在邮件内容的反垃圾判定上。多附件、超大图片、过于营销化的标题都有可能是触发点。这条链路排查下来基本能定位 90% 的“收不到”问题。剩下 10% 属于邮箱服务商之间的投递黑盒只能换发信渠道或提高内容质量规避。7.3 邮件内容编码与乱码问题涉及中文标题、中文文件名时Nodemailer 会自动处理编码绝大多数情况下不需要你操心。但如果你手动拼接了不规范的 Content-Disposition 头或附件文件名中包含特殊字符如空格、%、可能导致收件方收到的附件名乱码。稳妥做法是附件文件名用英文或数字或使用 Nodemailer 的 filename 字段让库自己处理编码。7.4 性能瓶颈与发送吞吐量优化在一次压力测试中我尝试过用单进程 Node.js 连续发送 1 万封邮件。最初没有加任何速率控制结果在第 800 多封时被 QQ 邮箱返回421错误后面的邮件全部排队失败。后来我加了rateLimit和maxConnections以每秒 20 封的速率重新测试顺利发完一万封没有再触发限流。如果你的需求是每天几万甚至几十万封单靠 Nodemailer 加连接池也不够建议引入专门的消息队列加多消费者实例同时考虑换用支持高吞吐的邮件 API 服务。这不是 Nodemailer 的短板而是 SMTP 协议本身与免费邮箱账号限制的客观边界。我在实际项目中体会最深的一点是邮件发送功能和普通业务接口的编写思路很不一样普通接口追求的是“快”邮件发送追求的是“稳”。发出去不代表结束你还要考虑速率限制、重试成本、幂等性、送达率。所以我把邮件功能的核心配置做成独立模块任何一个新项目需要接入邮件能力时直接复用这套代码换个环境变量就能上线这才算把通盘经验沉淀成了可复用的“标准作业程序”。最后再提一个小技巧接入 Nodemailer 后无论如何都要先拿真实邮箱做一次完整的全链路测试——发送文本、发送 HTML、发送带附件邮件、抄送、密送全程跑一遍。测试通过之后再接入业务代码能为你节省大量线上问题排查的时间。