接手某内部系统的第二周我被邮件模块整破防了。这个用 JavaMail 实现的邮件发送模块支撑着订单通知、告警提醒、报表推送各种场景但所有 HTML 格式邮件的模板全靠字符串拼接。新来的运营同事想改一句话得排期让我改代码想调整某个按钮颜色又是一轮打包部署。每次看那段几百行的 buildHtml 方法我都觉得这不是在维护代码而是在考古。后来我花了两个晚上用 JavaMail Thymeleaf 模板引擎把这个模块重写了。模板从 Java 字符串挪到独立的 HTML 文件里业务数据通过上下文对象注入邮件呈现实时预览、方便调试改版也不用动 Java 代码。这篇文章把完整的实现思路、关键代码和落地时踩过的坑都梳理一遍适合刚接手邮件发送模块的开发者以及那些还在用字符串拼接 HTML 邮件、想切换到模板方案的同学参考。1. 从字符串拼接邮件说起为什么一定要引入模板引擎1.1 邮件内容和代码耦合的尴尬先说我看到的那段历史代码长什么样。核心逻辑大概是这样的StringBuilder html new StringBuilder(); html.append(div style\font-family: Arial, sans-serif;\); html.append(h2尊敬的 ).append(userName).append(您好/h2); html.append(p您的订单 b).append(orderNo).append(/b 已发货。/p); if (remark ! null) { html.append(p备注).append(remark).append(/p); } html.append(a href\).append(detailUrl).append(\点击查看详情/a); html.append(/div);这段代码的问题相信大家一眼就能看出来第一可维护性极差。邮件模板本质上属于展示层现在和业务判断、数据组装全揉在一个方法里。产品经理想改一句话我得先读懂这段字符串拼接逻辑再小心翼翼地去动引号和加号一个转义字符写错线上邮件就直接花屏。第二HTML 转义很容易翻车。如果 userName 是用户在前台输入的昵称内容是scriptalert(1)/script直接拼进 HTML 里轻则样式错乱重则造成邮件内容注入收件人打开邮件看到各种异常展示甚至被钓鱼链接欺骗。正规做法是对用户内容做 HTML 转义但在字符串拼接的场景里人肉转义漏一次就是事故。第三改版成本高。运营说邮件顶部加个 banner 图前端切好图后端要把图片标签拼进 Java 字符串里运营说双十一换个促销横幅又得走一遍改代码、编译、部署的流程。明明只是改个展示层的东西却每次都牵动整个服务发布。1.2 JavaMail 与 Thymeleaf 组合能解决什么把 JavaMail 和 Thymeleaf 组合起来本质上是把发邮件这件事拆成两个边界清晰的部分JavaMail 负责传输建 Session、组装 MimeMessage、走 SMTP 协议把邮件交到收件方邮箱服务器。它不关心邮件长什么样、里边的数据从哪来。Thymeleaf 负责渲染把模板文件和后端传入的数据模型合并生成一段完整的 HTML 字符串。它不关心邮件怎么发出去只关心模板语法和数据填充。这样做的好处非常直接。模板文件独立放在src/main/resources/templates/mail/目录下前端同事直接打开就是一个带默认数据的静态页面所见即所得后端只需要往Context里塞数据然后调用一次渲染方法拿到 HTML 字符串交给 JavaMail 发送。改文案、改样式、加板块都不需要动 Java 代码。从技术原理上说Thymeleaf 的渲染结果本质就是字符串处理它和 JavaMail 的MimeMessageHelper.setText(html, true)方法无缝衔接。后面整个核心链路就是围绕模板字符串 - HTML 邮件内容 - MimeMessage这条主线展开的。2. 选型对比Thymeleaf 凭什么胜任邮件模板2.1 主流模板引擎在邮件场景的取舍在 Java 生态里能用来生成 HTML 的模板引擎不少常见的有 FreeMarker、Velocity及其后继者、Thymeleaf。我在做技术选型时简单对比过下面这个表格基本能说明问题引擎模板语法风格Spring Boot 契合度邮件场景特点现状Velocity#if#foreach指令风格一般需要额外配置传统方案老项目常见更新缓慢社区趋冷FreeMarker#if#list标签风格较好支持好写起来略显攻击性稳定仍有很多项目在用Thymeleafth:text属性风格默认集成开箱即用自然模板可直接浏览器预览官方活跃与 Spring 生态深度绑定核心考量是 Spring Boot 场景下的整合成本。spring-boot-starter-thymeleaf引入之后Spring Boot 自动配置好SpringTemplateEngine和模板解析器模板文件默认放在classpath:/templates/下几乎零配置就能跑起来。而 FreeMarker 虽然也挺好但多一个配置环节语法对后端开发者来说更像是在 HTML 里写标签不如 Thymeleaf 那种自然属性直观。2.2 Thymeleaf 的自然模板特性对邮件意味着什么Thymeleaf 有一个很独特的设计叫自然模板。简单说模板文件本身就是一个合法的静态 HTML 页面所有动态内容通过th:*属性标注。p th:text尊敬的 ${userName} 尊敬的 客户/p用浏览器直接打开这个文件不经过 Thymeleaf 渲染你看到的是尊敬的 客户经过渲染后看到的是尊敬的 张三。也就是说模板在没有后端数据的情况下依然可以预览这对邮件场景来说太宝贵了。邮件模板的审阅往往涉及运营、产品、前端多方协作他们大多不熟悉 Java也不方便启动整个后端服务。用 Thymeleaf 之后直接把 HTML 文件发给运营同事什么数据都不用准备浏览器打开就能看到大致布局和默认文案渲染后的效果最多就是默认示例数据替换成真实数据而已。这个特性是其他标签风格模板引擎做不到的。另外邮件模板还有一个独有的诉求模板里经常要写大量兼容邮件客户端的table布局和内联样式。Thymeleaf 对原生 HTML 标签完全透明不管多复杂的 table 嵌套、style 内联它都能原样输出只渲染带th:*属性的节点。这一点也让我最终选了它。3. 核心链路落地从模板文件到 MimeMessage 的全过程3.1 依赖引入和 SMTP 参数先让 Hello World 发出去我用的是 Spring Boot 项目依赖方面其实就两个 starter省去很多手工装配的麻烦dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependencyspring-boot-starter-mail内部封装了 JavaMail API并且自动配置出JavaMailSender这个 Beanspring-boot-starter-thymeleaf则自动配置出SpringTemplateEngine。两个 Bean 直接注入 Service 就能用。然后是application.yml里的 SMTP 配置。我拿公司内部邮箱系统举例参数基本是这几项spring: mail: host: smtp.example.com port: 587 username: it_serviceexample.com password: your-smtp-password default-encoding: UTF-8 properties: mail: smtp: auth: true starttls: enable: true timeout: 5000 connectiontimeout: 5000 writetimeout: 5000这里的port建议用 587 而不是 25。25 端口是传统 SMTP 端口很多云服务器默认封禁而且明文传输。587 配合 STARTTLS 是主流邮件服务商推荐的提交端口安全性和可达性都更好。timeout系列参数也建议加上不然默认 TCP 超时时间很长邮件服务不可用时接口会卡很久。3.2 模板渲染Thymeleaf 的 Context 与表达式模板文件我放在src/main/resources/templates/mail/order-notify.html。这个路径是 Spring Boot 自动配置的默认模板根目录不需要额外指定解析器。!DOCTYPE html html langzh xmlns:thhttp://www.thymeleaf.org head meta charsetUTF-8 / title订单发货通知/title /head body p th:text尊敬的 ${userName} 尊敬的 客户/p p您的订单 strong th:text${orderNo}订单号/strong 已发货。/p p th:text预计送达时间 ${deliveryTime}预计送达时间待定/p p th:if${remark ! null} th:text${remark}备注信息/p a th:href${detailUrl} hrefhttps://example.com/order/detail点击查看详情/a /body /html注意一个细节HTML 文件里我写了默认内容作为兜底。即使后端万一渲染失败或者有人直接用浏览器打开模板看到的也是一份结构完整的示例页面。这是 Thymeleaf 自然模板语法的优势在邮件模板协作场景里特别实用。渲染的核心代码如下Service public class MailService { private final JavaMailSender mailSender; private final SpringTemplateEngine templateEngine; public MailService(JavaMailSender mailSender, SpringTemplateEngine templateEngine) { this.mailSender mailSender; this.templateEngine templateEngine; } public void sendOrderNotify(String to, OrderNotifyData data) throws MessagingException { Context context new Context(); context.setVariable(userName, data.getUserName()); context.setVariable(orderNo, data.getOrderNo()); context.setVariable(deliveryTime, data.getDeliveryTime()); context.setVariable(remark, data.getRemark()); context.setVariable(detailUrl, data.getDetailUrl()); String html templateEngine.process(mail/order-notify, context); MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(it_serviceexample.com); helper.setTo(to); helper.setSubject(您的订单已发货); helper.setText(html, true); mailSender.send(message); } }这里用的是org.thymeleaf.context.Context而不是WebContext。原因很简单邮件渲染不依赖 HTTP 请求对象不是在处理用户请求的 Web 上下文直接用一个普通Context塞变量就够了。3.3 组装 MimeMessage真正容易翻车的环节很多第一次接触 JavaMail 的同学容易在MimeMessageHelper上栽跟头。先说一个最容易忽略的细节helper.setText(html, true)的第二个布尔参数表示内容是 HTML。如果不传这个trueJavaMail 会把内容当作纯文本text/plain发送。收件人打开邮件看到的不是渲染好的页面而是一堆带着尖括号的 HTML 源码。这个参数设置了之后MimeMessageHelper才会在 MIME 头里写入Content-Type: text/html;charsetUTF-8邮件客户端才会按 HTML 解析正文。第二个细节是new MimeMessageHelper(message, true, UTF-8)构造器的第一个布尔值true它表示这是一个 multipart 邮件。如果只发纯 HTML 文本不设也行但只要后面要发附件、要内嵌图片就一定要传true。这个参数的本质是告诉 Helper允许构建multipart/mixed或者multipart/related的 MIME 结构。我建议无论有没有附件统一传true避免以后加附件时忘了改构造器。第三个容易被忽略的细节是helper.setFrom(it_serviceexample.com)。有些 SMTP 服务商会校验发件人地址必须和认证账号一致不一致会直接报错Sender address rejected。如果遇到这种情况把发件人地址改成 SMTP 认证的账号即可。另外如果要显示一个更友好的发件人名称可以这样写helper.setFrom(it_serviceexample.com, 某系统通知);这里第二个参数的显示名会经过邮件编码处理收件人那边看到是某系统通知而不是一堆乱码。前提是构造器里的字符集已经指定为 UTF-8。整个链路走通之后我看到的效果是模板文件独立管理数据通过 Context 注入JavaMail 负责传输改动文案不再需要碰 Java 代码。这个体验和之前字符串拼接完全不是一个量级。4. 进阶处理内嵌图片、附件与邮件客户端兼容性4.1 给邮件加入内嵌图片的正确姿势业务中经常需要在邮件里放 logo、二维码、商品图。不少初接触邮件的同学第一反应是在模板里用img srchttps://xxx.com/logo.png外链图片。这样做有个很现实的问题不少邮件客户端默认拦截外链图片。收件人打开邮件看到的是一堆破框和叉号需要手动点击加载图片才能看到内容转化率直接打折扣。正确的做法是把图片作为内嵌资源随邮件一起发送。JavaMail 里对应的是MimeMessageHelper.addInline()方法ClassPathResource logoResource new ClassPathResource(mail-resources/logo.png); helper.addInline(logo, logoResource);模板里的 img 标签通过cid协议引用这个资源img srccid:logo alt公司 Logo styleheight: 40px; /cid就是 Content-IDaddInline(logo, logoResource)的字符串名为这个内嵌资源分配了一个 Content-ID邮件客户端看到srccid:logo就会去邮件的 multipart/related 部分查找对应的资源附件。整个过程不需要把图片上传到任何公网服务器图片只存在于邮件本身既避免了外链被拦截也保护了用户隐私。用 Thymeleaf 渲染时如果这个 cid 名称是动态变化的也可以用表达式生成img th:srccid: ${logoCid} srccid:logo /然后后端把logoCid设置为logo。不动态变化的场景直接用固定写法更简单我日常就是这么用的。4.2 附件添加与文件名中文编码附件用addAttachment添加用法也很直白helper.addAttachment(订单详情.txt, new ClassPathResource(mail-resources/order-detail.txt));但这里有一个隐藏很深的中文乱码问题。邮件头的文件名参数不允许直接出现非 ASCII 字符MimeMessageHelper默认对附件名做编码处理在部分客户端上能正常显示但某些严格模式的邮件服务器或老旧客户端会显示成乱码。稳妥做法是对文件名手动做 RFC 2047 编码String encodedFileName MimeUtility.encodeWord(订单详情.txt, UTF-8, B); helper.addAttachment(encodedFileName, new ClassPathResource(mail-resources/order-detail.txt));MimeUtility.encodeWord会把中文文件名编码为类似?UTF-8?B?xxxx?的格式邮件协议可以安全传输主流客户端也能正确解码显示。这个坑我在正式环境踩过一次当时收件人看到附件名是一串问号排查了半天最后发现就是少了这个编码。另外还要注意邮件大小限制。大部分邮箱服务商对单封邮件有 20MB~50MB 不等的限制SMTP 协议层也存在单封邮件大小的限制。附件很大的场景建议先压缩再发送或者改用上传到内部文件服务、邮件里附链接的替代方案。4.3 样式兼容别再把它当普通网页写做邮件模板和做 Web 页面是两套思路。Web 页面可以随意用 CSS 外部样式表、Flex 布局、JS 交互但邮件客户端的 HTML 渲染能力非常有限尤其小心 Outlook 桌面版——它用的是 Word 排版引擎对现代 CSS 的支持差到令人发指。客户端外部 CSSstyle块Flex/Grid内联样式网页邮箱大多数部分支持支持有限支持支持移动端主流邮件 App基本不支持部分支持不稳定支持Outlook 桌面版不支持不支持不支持支持Apple Mail支持支持部分支持支持从这张表能得出一个非常明确的结论无论什么客户端都稳定支持的是内联样式。所以邮件模板实际开发时我的做法是把样式直接写在每个标签的style属性上p stylemargin: 0 0 12px 0; color: #333333; font-size: 14px;正文段落/p另外还有几个经验布局尽量用 table 嵌套不要依赖 Flex 或 Grid。这几年主流客户端的 Flex 支持好了一些但为了绝对稳妥核心结构我用 table内联元素用 span。字体、颜色、行高全显式指定。邮件客户端默认字体差异很大你不指定它就按自己的默认样式渲染设计稿变样是必然的事。不要使用 JavaScript大多数邮件客户端直接忽略或拦截还有可能因此把邮件判为垃圾邮件。不要引用外部 CSS 文件费劲维护还大概率被剥掉。这套内联样式 table 布局的组合虽然原始但也是邮件场景里最可靠、最通用的方案。5. 上线前必须处理的坑从本地调试到投递成功5.1 中文乱码的三个排查点邮件中文乱码是很常见的问题我总结下来主要有三个排查点按先后顺序检查基本都能解决。第一个是SMTP 会话字符集。application.yml里记得设置spring.mail.default-encoding: UTF-8这是全局兜底字符集。第二个是MimeMessage 本身的字符集。构造MimeMessageHelper时显式传 UTF-8MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8);这一点容易被忽略的是要在构造 Helper 时指定而不是发完再指定。setSubject和setText在写入 MIME 头时已经使用了指定字符集晚了就来不及了。第三个是邮件主题和附件名的编码。邮件头 RFC 规定非 ASCII 字符要经过 MIME 编码转换MimeMessageHelper.setSubject内部会自动处理通常不用管但附件名建议像上文那样手工MimeUtility.encodeWord。排查顺序建议是先开 SMTP 调试日志看原始 MIME 结构再检查 Helper 构造器字符集最后检查附件编码。5.2 被判定垃圾邮件的常见原因邮件明明发送成功却被对方扔进垃圾箱这个问题比代码 Bug 更让人头疼。从我的经验看主要原因是这几个首先是SPF/DKIM/DMARC 记录缺失或配置错误。简单说收件方服务器会检查发件域名的 DNS 解析记录确认这封邮件确实是由该域名授权的服务器发出的。如果发件域名从不配置 SPF 记录或者发件 IP 不在授权范围内大量邮件会被判为可疑。这个问题属于运维和域名管理范畴开发同学排查时需要和运维确认域名解析记录。其次是发件内容和主题触发了反垃圾规则。比如主题和正文里频繁出现免费、优惠、点击链接、发票等营销敏感词或者 HTML 里只有一个大量图片、极少文字都容易命中规则。正常业务通知类邮件文案尽量平实图片和文字比例均衡。再次是发送频率和发送环境的信誉。一台服务器突然向同一域名发送大量邮件或者长时间无发送记录、突然高频发送都会被对方邮件系统判定为恶意行为。批次发送时建议加一个随机的延迟策略让发送时间尽量自然分布。5.3 没有真实邮箱服务商怎么本地测邮件很多开发同学遇到的问题是公司内网环境没有现成的 SMTP 服务或者不想拿真实邮箱一遍遍试。这里有两种方案。第一种最简单的是开启 JavaMail 的调试日志直观看 SMTP 交互过程spring: mail: properties: mail: debug: true打开之后控制台会打印客户端和 SMTP 服务器之间的完整对话包括 EHLO、AUTH LOGIN、DATA 传输等原始指令。发信失败时首先看这部分日志比盲猜高效得多。第二种适合自动化测试的是在本地起一个假的 SMTP 服务我在项目中用过 GreenMail。它就是一个纯本地运行的邮箱服务器不真正外发邮件收到的邮件可以在测试里直接抓取断言GreenMail greenMail new GreenMail(ServerSetupTest.SMTP); greenMail.start(); // 执行发送邮件的业务代码 MimeMessage[] messages greenMail.getReceivedMessages(); assertEquals(1, messages.length); String content (String) messages[0].getContent(); assertTrue(content.contains(您的订单已发货));本地测试时还会顺带验证附件、内嵌图片是否正确附加在 multipart 结构里。跑完测试自动停掉不会污染任何真实用户邮箱。6. 再聊两句实战体会这套JavaMail Thymeleaf方案上线之后我已经用了挺长时间最大的感受是邮件模板的维护成本直线下降。运营和前端同学直接改 HTML 文件改完提交给我预览确认基本不用等我排期。字符串拼接时代的那些转义噩梦、发布焦虑彻底成了历史。最后再分享一个我自己比较受用的小技巧模板渲染失败时不要直接吞异常。templateEngine.process如果模板变量缺失或表达式写错会抛出异常并明确指出哪个表达式、哪个模板片段出了问题。这时候把原始异常连同一份模板参数快照打印 Context 里的变量名列表一起记到日志里排查问题比看堆栈方便得多。另外如果邮件模板数量多、改动频繁可以考虑把模板放到配置中心或数据库中做成动态加载的版本后端连重启都省了。邮件发送这件事技术上没有多么高深但细节确实不少。只要把模板渲染和邮件传输的边界划清楚再把字符集、MIME 结构、图片附件这些环节处理好整套模块就能稳定跑很久。希望这份实践笔记能帮大家少踩一些我踩过的坑。 
长河君 · 2026/10/14 23:56:48 · 阅读 1.2k JavaMail集成Thymeleaf：告别字符串拼接的HTML邮件模板实践
接手某内部系统的第二周我被邮件模块整破防了。这个用 JavaMail 实现的邮件发送模块支撑着订单通知、告警提醒、报表推送各种场景但所有 HTML 格式邮件的模板全靠字符串拼接。新来的运营同事想改一句话得排期让我改代码想调整某个按钮颜色又是一轮打包部署。每次看那段几百行的 buildHtml 方法我都觉得这不是在维护代码而是在考古。后来我花了两个晚上用 JavaMail Thymeleaf 模板引擎把这个模块重写了。模板从 Java 字符串挪到独立的 HTML 文件里业务数据通过上下文对象注入邮件呈现实时预览、方便调试改版也不用动 Java 代码。这篇文章把完整的实现思路、关键代码和落地时踩过的坑都梳理一遍适合刚接手邮件发送模块的开发者以及那些还在用字符串拼接 HTML 邮件、想切换到模板方案的同学参考。1. 从字符串拼接邮件说起为什么一定要引入模板引擎1.1 邮件内容和代码耦合的尴尬先说我看到的那段历史代码长什么样。核心逻辑大概是这样的StringBuilder html new StringBuilder(); html.append(div style\font-family: Arial, sans-serif;\); html.append(h2尊敬的 ).append(userName).append(您好/h2); html.append(p您的订单 b).append(orderNo).append(/b 已发货。/p); if (remark ! null) { html.append(p备注).append(remark).append(/p); } html.append(a href\).append(detailUrl).append(\点击查看详情/a); html.append(/div);这段代码的问题相信大家一眼就能看出来第一可维护性极差。邮件模板本质上属于展示层现在和业务判断、数据组装全揉在一个方法里。产品经理想改一句话我得先读懂这段字符串拼接逻辑再小心翼翼地去动引号和加号一个转义字符写错线上邮件就直接花屏。第二HTML 转义很容易翻车。如果 userName 是用户在前台输入的昵称内容是scriptalert(1)/script直接拼进 HTML 里轻则样式错乱重则造成邮件内容注入收件人打开邮件看到各种异常展示甚至被钓鱼链接欺骗。正规做法是对用户内容做 HTML 转义但在字符串拼接的场景里人肉转义漏一次就是事故。第三改版成本高。运营说邮件顶部加个 banner 图前端切好图后端要把图片标签拼进 Java 字符串里运营说双十一换个促销横幅又得走一遍改代码、编译、部署的流程。明明只是改个展示层的东西却每次都牵动整个服务发布。1.2 JavaMail 与 Thymeleaf 组合能解决什么把 JavaMail 和 Thymeleaf 组合起来本质上是把发邮件这件事拆成两个边界清晰的部分JavaMail 负责传输建 Session、组装 MimeMessage、走 SMTP 协议把邮件交到收件方邮箱服务器。它不关心邮件长什么样、里边的数据从哪来。Thymeleaf 负责渲染把模板文件和后端传入的数据模型合并生成一段完整的 HTML 字符串。它不关心邮件怎么发出去只关心模板语法和数据填充。这样做的好处非常直接。模板文件独立放在src/main/resources/templates/mail/目录下前端同事直接打开就是一个带默认数据的静态页面所见即所得后端只需要往Context里塞数据然后调用一次渲染方法拿到 HTML 字符串交给 JavaMail 发送。改文案、改样式、加板块都不需要动 Java 代码。从技术原理上说Thymeleaf 的渲染结果本质就是字符串处理它和 JavaMail 的MimeMessageHelper.setText(html, true)方法无缝衔接。后面整个核心链路就是围绕模板字符串 - HTML 邮件内容 - MimeMessage这条主线展开的。2. 选型对比Thymeleaf 凭什么胜任邮件模板2.1 主流模板引擎在邮件场景的取舍在 Java 生态里能用来生成 HTML 的模板引擎不少常见的有 FreeMarker、Velocity及其后继者、Thymeleaf。我在做技术选型时简单对比过下面这个表格基本能说明问题引擎模板语法风格Spring Boot 契合度邮件场景特点现状Velocity#if#foreach指令风格一般需要额外配置传统方案老项目常见更新缓慢社区趋冷FreeMarker#if#list标签风格较好支持好写起来略显攻击性稳定仍有很多项目在用Thymeleafth:text属性风格默认集成开箱即用自然模板可直接浏览器预览官方活跃与 Spring 生态深度绑定核心考量是 Spring Boot 场景下的整合成本。spring-boot-starter-thymeleaf引入之后Spring Boot 自动配置好SpringTemplateEngine和模板解析器模板文件默认放在classpath:/templates/下几乎零配置就能跑起来。而 FreeMarker 虽然也挺好但多一个配置环节语法对后端开发者来说更像是在 HTML 里写标签不如 Thymeleaf 那种自然属性直观。2.2 Thymeleaf 的自然模板特性对邮件意味着什么Thymeleaf 有一个很独特的设计叫自然模板。简单说模板文件本身就是一个合法的静态 HTML 页面所有动态内容通过th:*属性标注。p th:text尊敬的 ${userName} 尊敬的 客户/p用浏览器直接打开这个文件不经过 Thymeleaf 渲染你看到的是尊敬的 客户经过渲染后看到的是尊敬的 张三。也就是说模板在没有后端数据的情况下依然可以预览这对邮件场景来说太宝贵了。邮件模板的审阅往往涉及运营、产品、前端多方协作他们大多不熟悉 Java也不方便启动整个后端服务。用 Thymeleaf 之后直接把 HTML 文件发给运营同事什么数据都不用准备浏览器打开就能看到大致布局和默认文案渲染后的效果最多就是默认示例数据替换成真实数据而已。这个特性是其他标签风格模板引擎做不到的。另外邮件模板还有一个独有的诉求模板里经常要写大量兼容邮件客户端的table布局和内联样式。Thymeleaf 对原生 HTML 标签完全透明不管多复杂的 table 嵌套、style 内联它都能原样输出只渲染带th:*属性的节点。这一点也让我最终选了它。3. 核心链路落地从模板文件到 MimeMessage 的全过程3.1 依赖引入和 SMTP 参数先让 Hello World 发出去我用的是 Spring Boot 项目依赖方面其实就两个 starter省去很多手工装配的麻烦dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependencyspring-boot-starter-mail内部封装了 JavaMail API并且自动配置出JavaMailSender这个 Beanspring-boot-starter-thymeleaf则自动配置出SpringTemplateEngine。两个 Bean 直接注入 Service 就能用。然后是application.yml里的 SMTP 配置。我拿公司内部邮箱系统举例参数基本是这几项spring: mail: host: smtp.example.com port: 587 username: it_serviceexample.com password: your-smtp-password default-encoding: UTF-8 properties: mail: smtp: auth: true starttls: enable: true timeout: 5000 connectiontimeout: 5000 writetimeout: 5000这里的port建议用 587 而不是 25。25 端口是传统 SMTP 端口很多云服务器默认封禁而且明文传输。587 配合 STARTTLS 是主流邮件服务商推荐的提交端口安全性和可达性都更好。timeout系列参数也建议加上不然默认 TCP 超时时间很长邮件服务不可用时接口会卡很久。3.2 模板渲染Thymeleaf 的 Context 与表达式模板文件我放在src/main/resources/templates/mail/order-notify.html。这个路径是 Spring Boot 自动配置的默认模板根目录不需要额外指定解析器。!DOCTYPE html html langzh xmlns:thhttp://www.thymeleaf.org head meta charsetUTF-8 / title订单发货通知/title /head body p th:text尊敬的 ${userName} 尊敬的 客户/p p您的订单 strong th:text${orderNo}订单号/strong 已发货。/p p th:text预计送达时间 ${deliveryTime}预计送达时间待定/p p th:if${remark ! null} th:text${remark}备注信息/p a th:href${detailUrl} hrefhttps://example.com/order/detail点击查看详情/a /body /html注意一个细节HTML 文件里我写了默认内容作为兜底。即使后端万一渲染失败或者有人直接用浏览器打开模板看到的也是一份结构完整的示例页面。这是 Thymeleaf 自然模板语法的优势在邮件模板协作场景里特别实用。渲染的核心代码如下Service public class MailService { private final JavaMailSender mailSender; private final SpringTemplateEngine templateEngine; public MailService(JavaMailSender mailSender, SpringTemplateEngine templateEngine) { this.mailSender mailSender; this.templateEngine templateEngine; } public void sendOrderNotify(String to, OrderNotifyData data) throws MessagingException { Context context new Context(); context.setVariable(userName, data.getUserName()); context.setVariable(orderNo, data.getOrderNo()); context.setVariable(deliveryTime, data.getDeliveryTime()); context.setVariable(remark, data.getRemark()); context.setVariable(detailUrl, data.getDetailUrl()); String html templateEngine.process(mail/order-notify, context); MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(it_serviceexample.com); helper.setTo(to); helper.setSubject(您的订单已发货); helper.setText(html, true); mailSender.send(message); } }这里用的是org.thymeleaf.context.Context而不是WebContext。原因很简单邮件渲染不依赖 HTTP 请求对象不是在处理用户请求的 Web 上下文直接用一个普通Context塞变量就够了。3.3 组装 MimeMessage真正容易翻车的环节很多第一次接触 JavaMail 的同学容易在MimeMessageHelper上栽跟头。先说一个最容易忽略的细节helper.setText(html, true)的第二个布尔参数表示内容是 HTML。如果不传这个trueJavaMail 会把内容当作纯文本text/plain发送。收件人打开邮件看到的不是渲染好的页面而是一堆带着尖括号的 HTML 源码。这个参数设置了之后MimeMessageHelper才会在 MIME 头里写入Content-Type: text/html;charsetUTF-8邮件客户端才会按 HTML 解析正文。第二个细节是new MimeMessageHelper(message, true, UTF-8)构造器的第一个布尔值true它表示这是一个 multipart 邮件。如果只发纯 HTML 文本不设也行但只要后面要发附件、要内嵌图片就一定要传true。这个参数的本质是告诉 Helper允许构建multipart/mixed或者multipart/related的 MIME 结构。我建议无论有没有附件统一传true避免以后加附件时忘了改构造器。第三个容易被忽略的细节是helper.setFrom(it_serviceexample.com)。有些 SMTP 服务商会校验发件人地址必须和认证账号一致不一致会直接报错Sender address rejected。如果遇到这种情况把发件人地址改成 SMTP 认证的账号即可。另外如果要显示一个更友好的发件人名称可以这样写helper.setFrom(it_serviceexample.com, 某系统通知);这里第二个参数的显示名会经过邮件编码处理收件人那边看到是某系统通知而不是一堆乱码。前提是构造器里的字符集已经指定为 UTF-8。整个链路走通之后我看到的效果是模板文件独立管理数据通过 Context 注入JavaMail 负责传输改动文案不再需要碰 Java 代码。这个体验和之前字符串拼接完全不是一个量级。4. 进阶处理内嵌图片、附件与邮件客户端兼容性4.1 给邮件加入内嵌图片的正确姿势业务中经常需要在邮件里放 logo、二维码、商品图。不少初接触邮件的同学第一反应是在模板里用img srchttps://xxx.com/logo.png外链图片。这样做有个很现实的问题不少邮件客户端默认拦截外链图片。收件人打开邮件看到的是一堆破框和叉号需要手动点击加载图片才能看到内容转化率直接打折扣。正确的做法是把图片作为内嵌资源随邮件一起发送。JavaMail 里对应的是MimeMessageHelper.addInline()方法ClassPathResource logoResource new ClassPathResource(mail-resources/logo.png); helper.addInline(logo, logoResource);模板里的 img 标签通过cid协议引用这个资源img srccid:logo alt公司 Logo styleheight: 40px; /cid就是 Content-IDaddInline(logo, logoResource)的字符串名为这个内嵌资源分配了一个 Content-ID邮件客户端看到srccid:logo就会去邮件的 multipart/related 部分查找对应的资源附件。整个过程不需要把图片上传到任何公网服务器图片只存在于邮件本身既避免了外链被拦截也保护了用户隐私。用 Thymeleaf 渲染时如果这个 cid 名称是动态变化的也可以用表达式生成img th:srccid: ${logoCid} srccid:logo /然后后端把logoCid设置为logo。不动态变化的场景直接用固定写法更简单我日常就是这么用的。4.2 附件添加与文件名中文编码附件用addAttachment添加用法也很直白helper.addAttachment(订单详情.txt, new ClassPathResource(mail-resources/order-detail.txt));但这里有一个隐藏很深的中文乱码问题。邮件头的文件名参数不允许直接出现非 ASCII 字符MimeMessageHelper默认对附件名做编码处理在部分客户端上能正常显示但某些严格模式的邮件服务器或老旧客户端会显示成乱码。稳妥做法是对文件名手动做 RFC 2047 编码String encodedFileName MimeUtility.encodeWord(订单详情.txt, UTF-8, B); helper.addAttachment(encodedFileName, new ClassPathResource(mail-resources/order-detail.txt));MimeUtility.encodeWord会把中文文件名编码为类似?UTF-8?B?xxxx?的格式邮件协议可以安全传输主流客户端也能正确解码显示。这个坑我在正式环境踩过一次当时收件人看到附件名是一串问号排查了半天最后发现就是少了这个编码。另外还要注意邮件大小限制。大部分邮箱服务商对单封邮件有 20MB~50MB 不等的限制SMTP 协议层也存在单封邮件大小的限制。附件很大的场景建议先压缩再发送或者改用上传到内部文件服务、邮件里附链接的替代方案。4.3 样式兼容别再把它当普通网页写做邮件模板和做 Web 页面是两套思路。Web 页面可以随意用 CSS 外部样式表、Flex 布局、JS 交互但邮件客户端的 HTML 渲染能力非常有限尤其小心 Outlook 桌面版——它用的是 Word 排版引擎对现代 CSS 的支持差到令人发指。客户端外部 CSSstyle块Flex/Grid内联样式网页邮箱大多数部分支持支持有限支持支持移动端主流邮件 App基本不支持部分支持不稳定支持Outlook 桌面版不支持不支持不支持支持Apple Mail支持支持部分支持支持从这张表能得出一个非常明确的结论无论什么客户端都稳定支持的是内联样式。所以邮件模板实际开发时我的做法是把样式直接写在每个标签的style属性上p stylemargin: 0 0 12px 0; color: #333333; font-size: 14px;正文段落/p另外还有几个经验布局尽量用 table 嵌套不要依赖 Flex 或 Grid。这几年主流客户端的 Flex 支持好了一些但为了绝对稳妥核心结构我用 table内联元素用 span。字体、颜色、行高全显式指定。邮件客户端默认字体差异很大你不指定它就按自己的默认样式渲染设计稿变样是必然的事。不要使用 JavaScript大多数邮件客户端直接忽略或拦截还有可能因此把邮件判为垃圾邮件。不要引用外部 CSS 文件费劲维护还大概率被剥掉。这套内联样式 table 布局的组合虽然原始但也是邮件场景里最可靠、最通用的方案。5. 上线前必须处理的坑从本地调试到投递成功5.1 中文乱码的三个排查点邮件中文乱码是很常见的问题我总结下来主要有三个排查点按先后顺序检查基本都能解决。第一个是SMTP 会话字符集。application.yml里记得设置spring.mail.default-encoding: UTF-8这是全局兜底字符集。第二个是MimeMessage 本身的字符集。构造MimeMessageHelper时显式传 UTF-8MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8);这一点容易被忽略的是要在构造 Helper 时指定而不是发完再指定。setSubject和setText在写入 MIME 头时已经使用了指定字符集晚了就来不及了。第三个是邮件主题和附件名的编码。邮件头 RFC 规定非 ASCII 字符要经过 MIME 编码转换MimeMessageHelper.setSubject内部会自动处理通常不用管但附件名建议像上文那样手工MimeUtility.encodeWord。排查顺序建议是先开 SMTP 调试日志看原始 MIME 结构再检查 Helper 构造器字符集最后检查附件编码。5.2 被判定垃圾邮件的常见原因邮件明明发送成功却被对方扔进垃圾箱这个问题比代码 Bug 更让人头疼。从我的经验看主要原因是这几个首先是SPF/DKIM/DMARC 记录缺失或配置错误。简单说收件方服务器会检查发件域名的 DNS 解析记录确认这封邮件确实是由该域名授权的服务器发出的。如果发件域名从不配置 SPF 记录或者发件 IP 不在授权范围内大量邮件会被判为可疑。这个问题属于运维和域名管理范畴开发同学排查时需要和运维确认域名解析记录。其次是发件内容和主题触发了反垃圾规则。比如主题和正文里频繁出现免费、优惠、点击链接、发票等营销敏感词或者 HTML 里只有一个大量图片、极少文字都容易命中规则。正常业务通知类邮件文案尽量平实图片和文字比例均衡。再次是发送频率和发送环境的信誉。一台服务器突然向同一域名发送大量邮件或者长时间无发送记录、突然高频发送都会被对方邮件系统判定为恶意行为。批次发送时建议加一个随机的延迟策略让发送时间尽量自然分布。5.3 没有真实邮箱服务商怎么本地测邮件很多开发同学遇到的问题是公司内网环境没有现成的 SMTP 服务或者不想拿真实邮箱一遍遍试。这里有两种方案。第一种最简单的是开启 JavaMail 的调试日志直观看 SMTP 交互过程spring: mail: properties: mail: debug: true打开之后控制台会打印客户端和 SMTP 服务器之间的完整对话包括 EHLO、AUTH LOGIN、DATA 传输等原始指令。发信失败时首先看这部分日志比盲猜高效得多。第二种适合自动化测试的是在本地起一个假的 SMTP 服务我在项目中用过 GreenMail。它就是一个纯本地运行的邮箱服务器不真正外发邮件收到的邮件可以在测试里直接抓取断言GreenMail greenMail new GreenMail(ServerSetupTest.SMTP); greenMail.start(); // 执行发送邮件的业务代码 MimeMessage[] messages greenMail.getReceivedMessages(); assertEquals(1, messages.length); String content (String) messages[0].getContent(); assertTrue(content.contains(您的订单已发货));本地测试时还会顺带验证附件、内嵌图片是否正确附加在 multipart 结构里。跑完测试自动停掉不会污染任何真实用户邮箱。6. 再聊两句实战体会这套JavaMail Thymeleaf方案上线之后我已经用了挺长时间最大的感受是邮件模板的维护成本直线下降。运营和前端同学直接改 HTML 文件改完提交给我预览确认基本不用等我排期。字符串拼接时代的那些转义噩梦、发布焦虑彻底成了历史。最后再分享一个我自己比较受用的小技巧模板渲染失败时不要直接吞异常。templateEngine.process如果模板变量缺失或表达式写错会抛出异常并明确指出哪个表达式、哪个模板片段出了问题。这时候把原始异常连同一份模板参数快照打印 Context 里的变量名列表一起记到日志里排查问题比看堆栈方便得多。另外如果邮件模板数量多、改动频繁可以考虑把模板放到配置中心或数据库中做成动态加载的版本后端连重启都省了。邮件发送这件事技术上没有多么高深但细节确实不少。只要把模板渲染和邮件传输的边界划清楚再把字符集、MIME 结构、图片附件这些环节处理好整套模块就能稳定跑很久。希望这份实践笔记能帮大家少踩一些我踩过的坑。