如何在Nodemailer中强制发送HTML邮件？环境差异问题排查

环境差异可能的原因 #

• HTML内容被转义：服务器环境中，body变量可能被模板引擎、中间件或自定义逻辑自动转义，导致<br>变成<br>，邮件客户端无法识别为HTML标签，直接显示纯文本。
• SMTP服务器MIME类型干预：本地和服务器使用的SMTP服务不同，部分服务商或自建SMTP服务器可能会自动修改邮件的Content-Type头，强制将邮件转为纯文本格式。
• 字符编码不一致：服务器的系统字符编码或应用编码设置与本地不同，导致HTML内容解析异常，被邮件客户端当作纯文本处理。
• 隐性text字段覆盖：虽然代码中注释了text: body，但服务器端可能存在其他逻辑动态添加了text字段。Nodemailer中若同时存在text和html，部分邮件客户端或SMTP服务器会优先选择纯文本展示。

强制发送HTML邮件的解决方法 #

1. 显式指定Content-Type并设置纯文本 fallback #

在mailOptions中明确声明邮件的MIME类型，同时提供纯文本版本作为降级方案，避免SMTP服务器自动转换格式：

const mailOptions = {
    from,
    to,
    subject,
    text: '请使用支持HTML的邮件客户端查看此邮件', // 纯文本备用内容
    html: body,
    headers: {
        'Content-Type': 'text/html; charset=utf-8'
    }
};

2. 检查并禁用HTML转义 #

• 若使用模板引擎（如EJS、Pug），确保渲染时未开启自动转义：比如EJS用<%- body %>而非<%= body %>，Pug关闭escape选项。
• 手动拼接HTML时，确认服务器端没有对body执行escape()、htmlspecialchars()等转义操作，打印body的实际值对比本地和服务器的差异。

3. 验证SMTP配置 #

检查服务器端的SMTP transporter配置，确保没有强制纯文本的设置：

• 若使用第三方SMTP服务（如SendGrid、Mailgun），登录服务商后台确认邮件格式设置为允许HTML。
• 自建SMTP服务器的话，检查邮件传输规则，禁止自动修改Content-Type头。

4. 开启调试模式排查原始邮件 #

启用Nodemailer的调试模式，查看发送的原始邮件头和内容，确认Content-Type是否正确设置：

const transporter = nodemailer.createTransport({
    // 你的SMTP配置（如host、port、auth等）
    debug: true, // 开启调试日志
    logger: true
});

5. 处理内联资源（若有） #

如果HTML中包含内联图片或样式，添加attachDataUrls: true确保资源被正确识别，避免客户端降级为纯文本：

const mailOptions = {
    // 其他配置
    html: body,
    attachDataUrls: true
};

内容的提问来源于stack exchange，提问作者dmikester1