nodemailer集成handlebars发送邮件时模板无法正常显示

高频配置错误修复（对应nodemailer-express-handlebars插件不加载模板问题） #

90%的插件不生效问题来自四个配置疏漏：

• 插件必须注册到Nodemailer的transporter实例，而非Express的app实例
• 模板路径必须使用Node.jspath模块生成绝对路径，禁止写相对路径，运行时工作目录变动会导致相对路径失效
• 未自定义layout模板时必须显式关闭默认layout配置，插件默认会查找不存在的layout文件导致静默渲染失败
• 模板变量必须放在mailOptions.context字段下，禁止直接挂载到mailOptions根层级；只要mailOptions中存在手动定义的html字段，插件会直接跳过模板渲染流程

正确配置参考：

// mailer.js
const nodemailer = require('nodemailer');
const hbsPlugin = require('nodemailer-express-handlebars');
const path = require('path');

const transporter = nodemailer.createTransport({
  // 替换为实际SMTP服务配置
  host: 'smtp.your-email-domain.com',
  port: 465,
  secure: true,
  auth: {
    user: 'sender@your-domain.com',
    pass: 'your-smtp-auth-code'
  }
});

// 挂载模板插件到transporter
transporter.use('compile', hbsPlugin({
  viewEngine: {
    extName: '.hbs',
    partialsDir: path.resolve(__dirname, 'views'),
    layoutsDir: path.resolve(__dirname, 'views'),
    defaultLayout: false // 无公共layout时必须加这行
  },
  viewPath: path.resolve(__dirname, 'views'),
  extName: '.hbs'
}));

// 发件配置示例
const mailOptions = {
  from: 'sender@your-domain.com',
  to: 'recipient@domain.com',
  subject: '订单状态通知',
  template: 'orders', // 对应views/orders.hbs，不要加文件后缀
  context: { // 所有模板变量全部放在context内
    data: {
      orderItems: [] // 实际订单数据
    }
  }
};

手动编译模板空白问题修复（对应Handlebars.compile后发件无内容问题） #

接口预览渲染正常但邮件空白，基本为以下三类低级错误：

• 误将Handlebars.compile返回的编译函数本身传入html字段，未传入执行编译函数后生成的HTML字符串
• mailOptions中同时定义了空值的text字段，部分邮件客户端会优先展示text字段内容覆盖HTML
• 编译模板时传入的上下文数据层级和模板中引用的层级不匹配，比如模板写{{#each data.orderItems}}，传参时漏了外层的data字段

正确手动编译写法参考：

const fs = require('fs');
const Handlebars = require('handlebars');
const path = require('path');

// 读取模板文件
const templateSource = fs.readFileSync(path.resolve(__dirname, 'views/orders.hbs'), 'utf-8');
const compile = Handlebars.compile(templateSource);
// 传入上下文执行编译，拿到最终HTML字符串
const finalHtml = compile({
  data: {
    orderItems: [] // 实际订单数据，层级必须和模板引用对应
  }
});

const mailOptions = {
  from: 'sender@your-domain.com',
  to: 'recipient@domain.com',
  subject: '订单状态通知',
  html: finalHtml // 必须传入编译执行后的字符串，不要传compile函数本身
  // 无纯文本需求时不要写text字段，避免内容覆盖
};

邮件客户端兼容排查 #

配置验证正确仍显示异常时，检查以下兼容问题：

• 模板样式必须写为标签内联style，不要写<style>标签内的全局样式，绝大多数网页端、客户端邮箱会自动过滤非内联CSS，导致页面错乱显示为空白
• 模板内引用的图片、资源必须使用公网可直接访问的绝对URL，禁止写本地相对路径
• 检查收件箱垃圾邮件目录，HTML结构异常的邮件会被归类为垃圾邮件，默认不加载外部图片、样式资源

内容的提问来源于stack exchange，提问作者pelotador.1