Node.js使用Nodemailer通过SMTP发送邮件教程
本篇Node.js使用Nodemailer通过SMTP发送邮件教程深入讲解从零开始的配置与实现,包括SMTP授权码获取、传输器创建、纯文本与HTML邮件发送、内联附件处理、端口与TLS协商机制及常见错误排查。
在 Node.js 服务端开发中,向用户发送邮箱激活链接、登录验证码、重置密码凭证或业务告警通知是一项基础且关键的需求。实现这一目标最规范、成熟且通用的方案,是借助开源组件 nodemailer 通过简单邮件传输协议(SMTP, Simple Mail Transfer Protocol)与目标邮件服务提供商建立安全会话。本文将从准备 SMTP 凭据开始,逐步完成传输器构建、文本与 HTML 邮件发送、内联资源及附件传递,并深入分析 465 与 587 端口的安全协商机制及生产环境故障排查方法。
一、SMTP 与 Nodemailer 核心工作机制
理解邮件发送的核心概念有助于在后续编码与排错时保持思路清晰。电子邮件系统遵循客户端-服务器(C/S)模型:Node.js 应用作为邮件提交代理(MSA/MUA),借助 SMTP 协议与中继邮件服务器(MTA)完成网络会话,再由中继服务器根据收件人域名的 MX 记录路由至最终的目标邮箱网关。
nodemailer 是 Node.js 生态中使用最为广泛的邮件分发库,其优势在于没有复杂的底层 C++ 原生编译依赖,完全基于纯 JavaScript 与 Node.js 内置的 net、tls 及 stream 模块构建。在 Nodemailer 的内部抽象中,包含两个核心概念:
- Transporter(传输器):管理底层的网络套接字(Socket)、TLS 安全握手、身份认证会话及连接池(Pool)。通过配置目标 SMTP 服务的域名、端口与认证信息,Transporter 充当通往外部邮件服务器的稳定管道。
- MailOptions(邮件载荷对象):描述单封邮件的具体信息,包括发件人(
from)、收件人(to)、抄送(cc)、主题(subject)、纯文本正文(text)、富文本超文本(html)以及附件数组(attachments)。
二、准备工作与安装配置
在编写实际发信代码前,需要完成运行环境初始化并从邮件服务商处获取合法的 SMTP 访问凭据。
1. 初始化 Node.js 工程并安装依赖
确保本地或服务器已安装 Node.js(推荐 LTS 版本 v16.x、v18.x 或更高版本)。在终端进入项目根目录,初始化 package.json 并安装 nodemailer:
# 初始化 Node.js 项目(若已存在项目可跳过)
npm init -y
# 安装 Nodemailer 模块
npm install nodemailer
如果项目使用 ECMAScript Modules (ESM),可以在 package.json 中声明 "type": "module",或者直接使用 CommonJS 的 require() 语法。本教程示例同时兼顾这两种方式,代码核心保持一致。
2. 获取 SMTP 服务的授权码凭据
现代邮件服务商出于安全考虑,均已禁止在第三方客户端或代码中直接使用用户的“网页端登录密码”。取而代之的是专用授权码(Application Specific Password)。
- QQ 邮箱 / 163 网易邮箱:登录邮箱网页版后,依次进入“设置” → “账户”,向下滚动找到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”选项,开启“POP3/SMTP服务”。系统会要求发送短信进行安全验证,验证成功后将生成一串 16 位的独立授权码。
- Gmail:需要在 Google 账号开启“两步验证”(2-Step Verification),随后在“安全性”设置中进入“应用专用密码”(App Passwords),为“邮件”生成独立的 16 位密码。
- 企业邮箱与云推送服务:如腾讯企业邮、阿里企业邮或阿里云“邮件推送(DirectMail)”,通常在管理控制台中可直接分配专属的发信域名、AccessKey 或 SMTP 专用密码。
邮箱授权码拥有代发邮件的最高权限。务必将其配置在服务器环境变量或 .env 文件中(配合 dotenv 模块读取),切勿直接硬编码在代码仓库并推送到公开 Git 仓库中。
三、从零构建基础发送程序
我们将按照“创建传输器 → 验证连接 → 组装信头与内容 → 异步发送”的标准路径编写发信脚本。
1. 编写完整发信代码
在项目目录下新建 send_mail.js 文件,写入以下完整代码:
// 引入 nodemailer 模块
const nodemailer = require('nodemailer');
// 1. 创建 SMTP 传输器实例
const transporter = nodemailer.createTransport({
host: 'smtp.qq.com', // 替换为所用邮件服务商的 SMTP 地址,如 163 邮箱填 smtp.163.com
port: 465, // 465 端口开启安全直连
secure: true, // 465 端口对应 secure 为 true;587 端口对应 false
auth: {
user: 'your_email@qq.com', // 你的发件人完整邮箱账号
pass: 'abcdefghijklmnop', // 邮箱服务商生成的 16 位专属授权码
},
});
// 2. 封装发送函数
async function sendWelcomeEmail() {
try {
// 可选:在正式发送前验证 SMTP 连接与身份凭据有效性
await transporter.verify();
console.log('SMTP 服务器连接与身份验证成功,准备投递邮件...');
// 3. 构建邮件载荷对象 (MailOptions)
const mailOptions = {
from: '"技术架构团队" <your_email@qq.com>', // 发件人显示名称与必须同源的邮箱地址
to: 'recipient@example.com', // 收件人地址,多个收件人可用逗号分隔或数组传入
subject: '系统账户注册与环境配置确认函', // 邮件主题
text: '您好!欢迎使用本系统。这是一封由 Node.js Nodemailer 发送的纯文本确认邮件。', // 纯文本正文
html: `
<div style="font-family: sans-serif; padding: 20px; color: #1e293b; background-color: #f8fafc; border-radius: 8px;">
<h2 style="color: #345e82; border-bottom: 2px solid #345e82; padding-bottom: 8px;">欢迎注册系统账户</h2>
<p>尊敬的用户,您好:</p>
<p>您的开发者账号已于系统后台就绪,请在 30 分钟内点击下方按钮激活您的环境:</p>
<p style="margin: 24px 0;">
<a href="https://example.com/activate?token=sample123"
style="background-color: #ad8060; color: #ffffff; padding: 10px 20px; text-decoration: none; border-radius: 4px; font-weight: bold;">
立即激活账户
</a>
</p>
<p style="font-size: 12px; color: #64748b;">若您未申请该操作,请忽略本邮件。</p>
</div>
`,
};
// 4. 执行异步发送并捕获响应
const info = await transporter.sendMail(mailOptions);
console.log('邮件发送成功!MessageId: %s', info.messageId);
console.log('服务端响应结果: %s', info.response);
} catch (error) {
console.error('邮件发送失败,捕获到异常:', error);
}
}
// 执行发信
sendWelcomeEmail();
2. 运行与验证
在终端中执行该脚本:
node send_mail.js
当配置正确且网络畅通时,控制台将输出如下示例结果:
[示例输出]
SMTP 服务器连接与身份验证成功,准备投递邮件...
邮件发送成功!MessageId: <c1f4b2a8-8e6d-2d4e-12fa-3098f98a2130@qq.com>
服务端响应结果: 250 Ok: queued as
此时检查收件箱,即可看到渲染优美的 HTML 富文本邮件。如果收件箱未看到,应检查收件方的“垃圾邮件箱”或拦截记录。
四、添加附件与内联图片 (CID)
在业务场景中,常常需要向用户随邮件附带账单 PDF、日志压缩包,或者在 HTML 正文中直接嵌入产品 Logo 图片。Nodemailer 提供了高度统一的 attachments 声明机制。
1. 附件发送配置
附件可以来源于本地文件路径、Buffer 数据流,甚至可以直接由字符串生成。示例代码如下:
const mailOptionsWithAttachments = {
from: '"业务结算平台" <your_email@qq.com>',
to: 'client@example.com',
subject: '2026年度业务账单及签署协议',
text: '请查收随信附带的 PDF 电子凭证。',
html: `
<p>您好,附件为本月业务账单,内嵌公司图标如下:</p>
<img src="cid:company_logo" style="width: 140px; height: auto;" />
<p>请核对附件中的账单与日志。</p>
`,
attachments: [
// 1. 本地文件作为标准附件下载
{
filename: 'monthly-report.pdf',
path: './files/report_2026.pdf', // 本地文件的实际存储路径
contentType: 'application/pdf',
},
// 2. 内存中的纯文本内容直接转为附件
{
filename: 'audit-summary.txt',
content: '时间戳: 2026-11-17, 校验状态: SUCCESS, 操作人: SYSTEM',
contentType: 'text/plain',
},
// 3. 内联图片(通过 cid 机制与 HTML 正文中的 <img src="cid:..."> 绑定)
{
filename: 'logo.png',
path: './assets/brand_logo.png',
cid: 'company_logo', // 必须与 HTML 中的 cid 值保持完全一致
},
],
};
使用 cid(Content-ID)方案嵌入图片,相比使用 Base64 Data URI 或外部图片链接有显著优势:Base64 会使邮件体积膨胀 33% 且部分老旧客户端(如 Outlook)会直接拦截 Base64 图片;而外部 URL 图片通常会被多数邮箱默认“阻止外部图像加载”。CID 是最标准、兼容性最好的内联呈现手段。
五、SMTP 传输协议与安全端口深度解析
在配置 SMTP 传输器时,port 与 secure 的组合常常引起开发者的混淆。选错参数组合会导致握手卡死、超时或者连接被远端直接重置。
1. 端口 465 与 587 的本质差异
| 对比维度 | 端口 465 (SMTPS) | 端口 587 (Submission / STARTTLS) | 端口 25 (标准中继) |
|---|---|---|---|
| 加密建立时机 | 隐式加密:TCP 建连后立刻启动 TLS 握手,全程加密。 | 显式升级:先建立明文 TCP,通过发送 STARTTLS 指令升级为 TLS。 | 默认为明文传输,可选协商加密。 |
| Nodemailer 配置 | port: 465, secure: true |
port: 587, secure: false |
port: 25, secure: false |
| 公有云出网限制 | 放行(各大云平台默认允许出站) | 放行(通用邮件提交标准通道) | 严格封禁(阿里云/腾讯云/AWS 默认封锁) |
| 典型应用场景 | 国内 QQ 邮箱、网易 163、腾讯企业邮等首选 | Gmail、国际中继服务商、自建 Postfix/Exim 提交 | 邮件服务器之间的互联路由(MTA 到 MTA) |
2. 为什么在云服务器上千万不能用 25 端口?
几乎所有主流公有云厂商(包括阿里云、腾讯云、华为云、AWS、Google Cloud)为了防止垃圾邮件泛滥、IP 地址被列入国际反垃圾黑名单(RBL),都在虚拟私有云(VPC)底层防火墙与边界路由器上强制阻断了所有实例的出站 25 端口访问。即使你在操作系统防火墙放行该端口,网络包也会在网关层被直接丢弃,在代码中表现为长时间挂起并最终抛出 ETIMEDOUT 错误。因此在云端部署 Node.js 服务时,必须将端口指定为 465 或 587。
六、生产环境连接池与高可用优化
在简单的测试脚本中,每次发信新建并销毁一个 Transporter 尚可接受;但在日发送量达到数千封的生产业务中,频繁的 TCP 三次握手与 TLS 加密计算会消耗大量 CPU 与网络往返时间(RTT)。
1. 开启连接池 (Connection Pool)
Nodemailer 内置了生产级连接池管理器。在 createTransport 选项中设置 pool: true 即可开启连接复用:
const poolTransporter = nodemailer.createTransport({
pool: true, // 开启连接池支持
host: 'smtp.exmail.qq.com',
port: 465,
secure: true,
auth: {
user: process.env.SMTP_USER,
pass: process.env.SMTP_PASS,
},
maxConnections: 5, // 最大同时并发连接数(避免触发服务商连接过载保护)
maxMessages: 100, // 单个连接上复用发送的最大邮件数后重建,防止服务端僵尸连接
rateDelta: 1000, // 配合 rateLimit 限制发信频控(1000 毫秒)
rateLimit: 10, // 每秒最多发送 10 封,平滑突发流量
});
2. 异步架构解耦与重试
SMTP 通信涉及跨网传输,其响应时间通常在 300ms 到 2000ms 不等。严禁在 Web 接口(如 Express/Koa/NestJS 的 HTTP 请求处理函数)中同步 await 发送邮件。若遇到 SMTP 服务商偶发网络抖动,会导致用户的 HTTP 请求大量堆积,甚至造成 Node.js 事件循环拥堵与接口超时。
推荐工程实践:将发信任务作为消息放入异步作业队列(如基于 Redis 的 BullMQ 或 RabbitMQ),由后台专属的 Worker 进程消费队列、调用 Nodemailer 发送,并配置指数退避的自动重试机制。
七、常见报错原因与排查方案
在实际接入 SMTP 过程中,开发者常遇到四类经典异常。按照以下决策路径可快速定位并修复:
1. ETIMEDOUT 或 ECONNREFUSED(连接超时或连接被拒绝)
- 排查 1:确认当前是否使用了
port: 25。如在云服务器环境中,应立即修改为port: 465, secure: true。 - 排查 2:在服务器终端运行探测命令(如
nc -zv smtp.qq.com 465或telnet smtp.qq.com 465),确认安全组出方向是否放行了对应的 TCP 端口。
2. 535 Error: authentication failed(身份鉴权失败)
- 排查 1:核对
auth.pass是否填写成了个人登录密码。对于 QQ、163、126 等主流服务商,必须是单独申请生成的 16 位授权码。 - 排查 2:检查
auth.user是否填写了完整的邮箱后缀(例如user@qq.com,不能只写纯数字 QQ 号)。 - 排查 3:检查授权码字符串首尾是否意外混入了空格或换行符。
3. SELF_SIGNED_CERT_IN_CHAIN(自签名证书错误)
如果连接的是自建的内部邮件服务器或本地测试开发环境(如 MailHog/Mailpit),Node.js 的底层 TLS 机制会默认校验 CA 根证书链。如果使用的是自签名证书,会报此错误。临时开发测试可以通过配置 TLS 选项忽略校验:
const testTransporter = nodemailer.createTransport({
host: 'mail.internal.local',
port: 587,
secure: false,
tls: {
// 仅在本地开发调试或内网可信自建服务中使用,公网生产环境严禁关闭
rejectUnauthorized: false,
},
});
4. 550 / 554 Mailbox unavailable / Spam rejected(被拒收或反垃圾拦截)
- 原因 1:
mailOptions.from填写的邮箱与auth.user账号不一致。许多服务商强制要求发信人地址与鉴权身份严格同源,防止伪造身份。 - 原因 2:邮件内容过于简略(例如仅有一句“测试”或全是无意义字符),或者仅有 HTML 没有附带
text纯文本降级正文,触发了邮件反垃圾网关的贝叶斯过滤规则。
八、总结与技术速查清单
通过 Nodemailer 发送邮件是 Node.js 全栈与后端开发的核心基础技能。归纳其关键路径:首先确认服务商的 SMTP 地址与授权码,其次根据部署环境准确选定 465 (SSL) 或 587 (STARTTLS) 端口,接着构建包含纯文本与 HTML 降级支持的邮件实体,并在生产环境中引入连接池与异步队列进行削峰与容错。
- 必须授权码:绝不使用账号明文登录密码,仅使用 SMTP 独立授权码。
- 首选 465 端口:公有云上规避 25 端口封锁,优先设置
port: 465, secure: true。 - 同源约束:
from字段中的邮件地址必须与auth.user保持同源匹配。 - 正文双重降级:每次发送富文本 HTML 邮件时,务必同时提供对应的
text纯文本。 - 生产必开连接池:设置
pool: true,结合队列解耦,保障核心 HTTP 接口高可用与高响应性。
Node.js异步创建文件的最佳实践:async/await用法
2026-11-17 18:00:50
前端JS生成图片验证码后怎么与后端校验交互
2026-11-17 17:30:11
Node.js v27.0.0-alpha.0.1.1 为什么要区分压缩包与公证文件?
2026-11-17 13:27:27
TensorFlow.js与Brain.js对比:怎么选择合适的JavaScript神经网络库
2026-11-16 18:13:27
Node.js官网下载速度慢?使用官方镜像节点加速下载
2026-11-13 23:52:19








