Node.js使用Nodemailer通过SMTP发送邮件教程

作者:后端茶话

时间:2026-11-18

浏览:523

本篇Node.js使用Nodemailer通过SMTP发送邮件教程深入讲解从零开始的配置与实现,包括SMTP授权码获取、传输器创建、纯文本与HTML邮件发送、内联附件处理、端口与TLS协商机制及常见错误排查。

文章目录

在 Node.js 服务端开发中,向用户发送邮箱激活链接、登录验证码、重置密码凭证或业务告警通知是一项基础且关键的需求。实现这一目标最规范、成熟且通用的方案,是借助开源组件 nodemailer 通过简单邮件传输协议(SMTP, Simple Mail Transfer Protocol)与目标邮件服务提供商建立安全会话。本文将从准备 SMTP 凭据开始,逐步完成传输器构建、文本与 HTML 邮件发送、内联资源及附件传递,并深入分析 465 与 587 端口的安全协商机制及生产环境故障排查方法。

Node.js使用Nodemailer通过SMTP发送邮件教程
概览图:Node.js 结合 Nodemailer 通过 SMTP 协议发送邮件的技术架构与关键属性

一、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)。
Node.js使用Nodemailer通过SMTP发送邮件教程
图 1:Node.js 客户端通过 Nodemailer 与 SMTP 邮件服务器交互系统拓扑与数据流图

二、准备工作与安装配置

在编写实际发信代码前,需要完成运行环境初始化并从邮件服务商处获取合法的 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 仓库中。

Node.js使用Nodemailer通过SMTP发送邮件教程
图 2:Nodemailer 发送邮件四步核心实操流程

三、从零构建基础发送程序

我们将按照“创建传输器 → 验证连接 → 组装信头与内容 → 异步发送”的标准路径编写发信脚本。

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 的组合常常引起开发者的混淆。选错参数组合会导致握手卡死、超时或者连接被远端直接重置。

Node.js使用Nodemailer通过SMTP发送邮件教程
图 3:SMTP 端口 465 (SMTPS) 与 587 (STARTTLS) 握手时序与参数规范对比图

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 过程中,开发者常遇到四类经典异常。按照以下决策路径可快速定位并修复:

Node.js使用Nodemailer通过SMTP发送邮件教程
图 4:Nodemailer 常见发信错误排查与定位决策流

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 降级支持的邮件实体,并在生产环境中引入连接池与异步队列进行削峰与容错。

Node.js使用Nodemailer通过SMTP发送邮件教程
图 5:主流服务商参数矩阵与生产上线检查清单全景速查图
最终速查总结要点
  1. 必须授权码:绝不使用账号明文登录密码,仅使用 SMTP 独立授权码。
  2. 首选 465 端口:公有云上规避 25 端口封锁,优先设置 port: 465, secure: true。
  3. 同源约束:from 字段中的邮件地址必须与 auth.user 保持同源匹配。
  4. 正文双重降级:每次发送富文本 HTML 邮件时,务必同时提供对应的 text 纯文本。
  5. 生产必开连接池:设置 pool: true,结合队列解耦,保障核心 HTTP 接口高可用与高响应性。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章