2026/9/7 23:00:05
FEATURED · 精选文章 
SpringBoot整合邮件发送这事我前后在好几个项目里都搭过从最开始用原生 JavaMail API 手写工具类到后来换成spring-boot-starter-mail全家桶踩过的坑确实不少。最典型的一个是刚上手时配置文件里的主机端口对着网上抄结果发不出去连个像样的报错都没有后来开了 debug 日志才看到是加密协商方式不对。这篇就把 SpringBoot 整合 Email 邮件发送这套完整捋一遍从环境准备、配置项拆解、纯文本/HTML/附件/模板邮件写法到异步化处理和疑难问题排查全部给到你无论你是刚接触 SpringBoot 的新人还是想系统梳理邮件这块的老手都能直接拿来用。1. 项目整体思路与方案选型1.1 需求场景分析邮件发送在真实项目里几乎是刚需。注册验证码、密码找回、订单状态变更提醒、定时报表推送、告警通知这些场景都会走到发邮件这一步。不同场景对邮件功能的要求差别很大验证码、通知类纯文本或简单 HTML 就行要求发送速度快、不能阻塞主业务流程。营销、报表类需要模板渲染带着图片、附件内容要漂亮发送量大。告警类对可靠性要求高发送失败要有重试和补偿机制。所以在动手写代码之前先想清楚自己到底要做哪种这会直接影响后面是选SimpleMailMessage还是MimeMessageHelper要不要上消息队列要不要做重试。1.2 邮件协议基础SMTP、POP3、IMAP邮件发送最常见的协议是 SMTPSimple Mail Transfer Protocol负责把邮件从客户端送到邮件服务器再由服务器转发到对方的邮箱。SpringBoot 整合 Email 时JavaMailSender底层就是在跟 SMTP 服务器打交道。POP3 和 IMAP 是收件协议发邮件的时候基本用不到。但有一个点很关键很多邮箱服务商比如 QQ 邮箱、163 邮箱默认关闭了 SMTP 服务你需要在邮箱设置里手动开启 SMTP 服务并获取一个“授权码”用它代替登录密码来完成认证。这个授权码不是你的邮箱密码是服务商单独生成的一串口令专门给第三方客户端用。关于端口有个容易出错的地方常见的 SMTP 端口是 25、465、587。25 端口是传统 SMTP 端口很多云厂商默认封禁465 是 SSL 加密端口587 是 STARTTLS 加密端口。SpringBoot 配置里如果写 465通常需要配上mail.smtp.ssl.enabletrue这类参数写 587 则要开启STARTTLS混着用就会连不上或者认证失败。具体用哪个以邮箱服务商文档为准。1.3 选型对比spring-boot-starter-mail 为什么是首选市面上做邮件发送的 Java 方案不少直接用javax.mailJavaMail API、spring-boot-starter-mail、Apache Commons Email、jmail 等第三方组件还有各种云厂商的邮件推送服务。spring-boot-starter-mail是 Spring Boot 官方提供的封装底层还是 JavaMail但它做了大量自动配置和封装把复杂细节吞掉了。比如你只要在application.yml里配好spring.mail相关属性Spring Boot 会自动创建JavaMailSenderImpl这个 Bean直接注入到你的业务代码里就能用不需要手动创建 Session、配置 Store 之类的对象。相对 jmail 这类组件它的优势是跟 Spring 生态无缝集成支持Async、支持MimeMessageHelper这种丰富的消息构造工具社区资料也多。如果是特别大规模、对送达率要求极高的营销邮件建议用云厂商的邮件推送服务但绝大多数业务系统内部的通知、验证码、报表邮件spring-boot-starter-mail完全够用代码干净、维护成本低。2. 环境准备与基础配置2.1 依赖引入与版本选择在pom.xml里加依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency不需要手动写版本号SpringBoot 父工程已经管理了版本。我用的是 SpringBoot 2.7.x 和 3.x 都可以代码写法基本一致。唯一要注意的是 SpringBoot 3.x 里 JavaMail 使用的包名从javax.mail变成了jakarta.mail不过只要用 Spring 封装好的JavaMailSender和MimeMessageHelper这个问题基本感知不到底层已经帮你处理了。如果你的项目还要用 Thymeleaf 渲染模板邮件额外加一个依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency2.2 application.yml 配置参数逐项拆解拿 QQ 邮箱举例最小可用的配置长这样spring: mail: host: smtp.qq.com port: 465 username: your_accountqq.com password: your_auth_code protocol: smtp properties: mail: smtp: auth: true ssl: enable: true socketFactory: class: javax.net.ssl.SSLSocketFactory这里每个参数我都说一下我的理解spring.mail.hostSMTP 服务器地址。QQ 邮箱是smtp.qq.com163 是smtp.163.com企业微信邮箱是smtp.exmail.qq.com阿里企业邮箱是smtp.qiye.aliyun.com。spring.mail.port加密端口。QQ 邮箱和 163 都支持 465SSL和 587STARTTLS我习惯用 465。spring.mail.username发件邮箱完整地址。spring.mail.password这里填的不是邮箱登录密码是授权码。很多人卡在这一步后面单独说。spring.mail.protocol默认就是smtp可以不写。properties.mail.smtp.auth是否开启 SMTP 认证必须为true。properties.mail.smtp.ssl.enable和socketFactory.class465 端口下开启 SSL 加密。有些服务商要求必须指定SSLSocketFactory否则会报Could not convert socket to TLS之类的错误。另外有一个调试利器建议加上spring: mail: properties: mail: debug: true开启后控制台会打印完整的 SMTP 协议交互过程包括客户端和服务器之间的EHLO、AUTH LOGIN、MAIL FROM、RCPT TO、DATA等指令。排查连接不上、认证失败问题时非常有用定位完再关掉就行。2.3 授权码的获取与配置安全以 QQ 邮箱为例登录网页版 QQ 邮箱进入“设置” - “账户”找到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”开启“SMTP服务”这时候会要求发送一条短信验证验证通过后会给出一串授权码复制保存下来填到配置里注意不要用邮箱的登录密码。163 邮箱类似在“设置” - “POP3/SMTP/IMAP”里开启服务设置客户端授权密码。企业邮箱一般需要管理员在后台开启“SMTP 服务”并生成专属密码或授权码。有几个安全细节值得注意授权码相当于邮箱的“半把钥匙”不要提交到 Git 仓库。我一般会把配置外置到application-prod.yml或者用环境变量加载password: ${MAIL_PASSWORD}。不要把授权码硬编码在代码里更不要打印在日志中。如果公司有配置中心Nacos、Apollo 等建议把邮件配置放配置中心管理方便动态调整也避免密钥泄露。3. 核心功能实现从纯文本到模板附件3.1 最简单的纯文本邮件先创建一个邮件服务类核心就是注入JavaMailSender然后构造SimpleMailMessageService public class MailService { private final JavaMailSender mailSender; public MailService(JavaMailSender mailSender) { this.mailSender mailSender; } public void sendSimpleMail(String to, String subject, String text) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(your_accountqq.com); message.setTo(to); message.setSubject(subject); message.setText(text); mailSender.send(message); } }setFrom这里有个坑有些邮箱服务商要求发件人地址必须跟配置里的spring.mail.username一致否则会报553 Mail from must equal authorized user错误。如果你确实想用别的显示名称可以用这种写法message.setFrom(your_accountqq.com);或者如果你用的是 JavaMailSenderImpl 的MimeMessageHelper可以这样helper.setFrom(your_accountqq.com, 技术小站);指定了发件人姓名后对方收件箱里显示的就是“技术小站”而不是冷冰冰的邮箱地址。调用方式很简单在业务代码里注入MailService直接调sendSimpleMail(someoneexample.com, 测试主题, 测试内容)即可。但我这里提个醒这个写法是同步的如果邮件服务响应慢你的接口就会跟着变慢后面 3.4 节会讲怎么改造成异步。3.2 HTML 邮件与模板渲染纯文本邮件能解决“能发”的问题但要发漂亮的营销邮件、报表就得用 HTML。Spring 提供了MimeMessageHelper用起来也简单public void sendHtmlMail(String to, String subject, String html, String fromName) { try { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_accountqq.com, fromName); helper.setTo(to); helper.setSubject(subject); helper.setText(html, true); mailSender.send(message); } catch (MessagingException | UnsupportedEncodingException e) { log.error(发送HTML邮件失败, e); throw new RuntimeException(e); } }注意两点new MimeMessageHelper(message, true, UTF-8)第二个参数true表示 multipart 模式支持附件和内嵌资源第三个参数指定编码为 UTF-8避免中文乱码。实际项目里我基本不会在代码里拼 HTML 字符串那样维护性太差改用模板引擎。最常见的组合是 SpringBoot ThymeleafService public class TemplateMailService { private final JavaMailSender mailSender; private final SpringTemplateEngine templateEngine; // 构造器注入省略 public void sendTemplateMail(String to, String subject, MapString, Object params) { Context context new Context(); context.setVariables(params); String content templateEngine.process(mail/order-notify.html, context); try { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_accountqq.com, 商城系统); helper.setTo(to); helper.setSubject(subject); helper.setText(content, true); mailSender.send(message); } catch (MessagingException | UnsupportedEncodingException e) { log.error(发送模板邮件失败, e); throw new RuntimeException(e); } } }对应的模板文件src/main/resources/templates/mail/order-notify.html!DOCTYPE html html langzh xmlns:thhttp://www.thymeleaf.org body h3 th:text你好 ${userName} 你好用户/h3 p您的订单 span th:text${orderNo}202501010001/span 已发货请注意查收。/p /body /html参数通过Map传进去模板里用${}占位。这样做的好处是前端同学可以独立调整邮件样式不会影响后端逻辑。我还试过用 Freemarker 替代 Thymeleaf原理类似选哪个看你项目里已有的技术栈别单独为了邮件再引入一套。3.3 附件与内嵌图片邮件带附件的邮件要用到MimeMessageHelper.addAttachment方法public void sendAttachmentMail(String to, String subject, String content, File attachment) { try { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_accountqq.com); helper.setTo(to); helper.setSubject(subject); helper.setText(content); // 添加附件 helper.addAttachment(MimeUtility.encodeText(attachment.getName()), attachment); mailSender.send(message); } catch (MessagingException | UnsupportedEncodingException e) { log.error(发送附件邮件失败, e); } }上面代码里我用了MimeUtility.encodeText(attachment.getName())这一步很关键。如果你直接helper.addAttachment(attachment.getName(), attachment)中文文件名在部分邮箱客户端里会显示成乱码。用MimeUtility.encodeText对文件名进行 RFC 2047 编码后绝大多数客户端都能正确显示中文附件名。内嵌图片是另一种场景比如邮件里直接显示一张带二维码的图片而不是附件。做法是用addInlinehelper.setText(htmlbody请扫描二维码img srccid:qrCode//body/html, true); ClassPathResource resource new ClassPathResource(static/qrcode.png); helper.addInline(qrCode, resource);注意 HTML 里要用cid:qrCode引用图片addInline的第一个参数跟cid后面的名字保持一致。图片会作为邮件内嵌资源发送而不是附件下载。附件大小要留意普通邮箱服务器一般限制单个邮件总大小在 20MB 到 50MB 不等超出会被服务器拒绝。如果业务上有大文件附件需求建议先传对象存储OSS/COS然后在邮件里放下载链接别直接塞附件。3.4 异步化改造别让邮件拖垮接口邮件发送涉及网络 IO如果同步执行请求方会一直等到邮件服务器响应才返回。注册接口里如果同步发验证码用户体验会非常差。解决办法就是异步化。SpringBoot 里最简单的方式是加Async注解。先开启异步支持Configuration EnableAsync public class AsyncConfig { Bean(mailExecutor) public Executor mailExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(5); executor.setQueueCapacity(100); executor.setThreadNamePrefix(mail-thread-); executor.initialize(); return executor; } }然后在发邮件的方法上指定线程池Async(mailExecutor) Override public void sendSimpleMail(String to, String subject, String text) { // 实际发送逻辑 }需要注意两点Async生效的前提是方法被 Spring 代理调用所以不能同类内部调用也就是说你不能在同一个类里写完一个普通方法又直接调另一个带Async的方法另外异步方法里如果抛异常调用方式是感知不到的所以建议在方法内部捕获异常做好日志和补偿记录。做异步之后要思考一个问题如果发送失败怎么办我的做法是给异步方法加一个发送失败的重试机制最简单的方式是用Retryable或在方法内部手动捕获异常并按次数重试。更稳妥一点可以把发送任务落到数据库做成一张mail_send_record表记录收件人、主题、内容、发送状态和重试次数由定时任务扫描失败的记录重新发送。这样才能保证业务系统不发漏邮件。4. 常见问题、避坑经验与高频面试考点4.1 高频报错速查表邮件发送的问题一般不难定位难的是你连报错都不看就瞎试。我把自己实测过的报错整理成了表格给新手朋友当个对照表用报错信息原因解决办法AuthenticationFailedException用户名或授权码错误检查spring.mail.password是否为授权码不是登录密码SocketException: Connection reset端口和加密方式不匹配465 端口配 SSL587 端口配 STARTTLSMessagingException: Unknown SMTP hosthost 配置错误确认邮箱服务商 SMTP 地址是否写对MailSendException: Couldnt connect to host网络不通或端口被封检查防火墙、云厂商安全组是否放行对应端口553 Mail from must equal authorized user发件人与认证用户不一致setFrom地址必须跟spring.mail.username一致501 Syntax error in parameters or arguments邮件地址格式错误检查收件人地址是否为空、格式是否正确Invalid Addresses收件人地址非法检查setTo传的是不是邮箱地址多个用逗号分隔这里特别提醒一点看到MailSendException不要慌先开spring.mail.properties.mail.debugtrue看协议日志里具体是哪一步失败。常见的是在AUTH LOGIN之后就断了那就一定是认证问题如果卡在MAIL FROM或RCPT TO那基本是校验失败比如发件人不一致或收件人格式不对。协议日志会把问题展示得明明白白。4.2 那些年我踩过的邮件坑聊几个平时文档里不会写那么细的坑都是我实际碰到过的。第一个坑是只有一个收件人的时候用setTo(String)多个收件人用setTo(String...)但如果你不小心传了一个空字符串进去就会报 Invalid Addresses。而且这个报错有时候不会立刻暴露邮件服务器那边可能在 DATA 阶段才拒绝排查起来很绕。我的习惯是封装一个校验方法在调用mailSender.send之前先检查一下收件人列表是否为空这个检查成本极低收益却很明显。第二个坑是启动时如果配置不对SpringBoot 项目并不会启动失败而是等你真正调用send方法时才抛异常。这就导致很多人以为自己配置好了结果上线接口一调就炸。应对办法是加一个启动检查的ApplicationRunner项目启动时用配置的发件人给自己发一封测试邮件发不出去就启动失败把问题挡在测试环境。第三个坑是高并发下的连接池问题。JavaMailSenderImpl默认不会复用连接每次发送都建立新的 SMTP 连接如果发信量大会频繁建连、断连性能很差。可以配置连接池比如在spring.mail.properties里设置mail.smtp.connectiontimeout和mail.smtp.timeout或者使用 Commons Pool 复用Transport连接。不过绝大多数业务系统的发信量到不了这一步如果真到这一步建议直接换成云邮件推送服务省心得多。第四个坑是附件名和文件名中文乱码问题。有的同学配置了 UTF-8 编码正文显示没问题但附件名还是乱码原因就在addAttachment传原始文件名时没有做 RFC 2047 编码。这个问题在不同邮箱客户端显示不一致Outlook 和 Gmail 的处理方式还不一样保险起见统一用MimeUtility.encodeText处理。第五个坑是发送频率限制。无论是 QQ 邮箱还是 163 邮箱日常账号都有每天发信量上限一般在每天几百封到上千封不等。如果你的业务是群发营销邮件用普通邮箱账号发很容易触发风控轻则进垃圾箱重则封禁 SMTP 功能。这种场景必须用企业邮箱或云邮件推送服务来解决。4.3 顺带聊聊 SpringBoot 邮件相关的面试考点热词里出现了“springboot面试题”我猜有不少读者其实是在准备面试。邮件发送这个功能虽然简单但面试官特别喜欢从里面挖几个点第一个问题是“SpringBoot 的邮件自动配置是怎么做到的”。答案核心是MailSenderAutoConfiguration。它在classpath存在javax.mail.internet.MimeMessage并且容器里没有JavaMailSenderBean 时会根据spring.mail前缀的属性创建JavaMailSenderImpl。这就是为什么你只加一个依赖、写几行配置就能注入JavaMailSender。第二个问题是“JavaMailSender和JavaMailSenderImpl的区别”。JavaMailSender是接口JavaMailSenderImpl是它的实现类。平时注入接口就行但如果你想在运行时动态修改配置比如同一个系统要切换不同发件人可以拿到JavaMailSenderImpl实例调用setUsername、setPassword动态修改。第三个问题是“如何确保邮件不丢失”。这个问题没有标准答案但能考察系统设计能力。基本的思路是发送任务持久化到数据库设置状态字段发送成功后更新状态发送失败记录错误原因并定时补偿。更进阶的方案是用 MQ 削峰把发送请求异步写入队列消费者慢慢处理再配合失败重试和告警。第四个问题是“MimeMessageHelper为什么必须指定 UTF-8”。因为邮件消息的编码规则比较复杂如果不显式指定 charset可能使用平台默认编码遇到中文内容就会乱码。指定 UTF-8 是跨平台、跨邮件客户端最稳妥的做法。第五个问题是“多个收件人如何做到互相不可见”。互不可见要用密送setBcc而不是setCc。面试官可能会追问两者差别Cc抄送的收件人能看到其他收件人地址Bcc密送的收件人看不到其他收件人地址适合群发场景能保护用户隐私。这些考点本身不难但能把自动配置原理和异常处理机制聊清楚的人确实不多你如果能把实际踩坑的经验一起讲出来面试官会高看你一眼。我自己的经验是邮件功能看着简单真正要做到稳、快、不丢还是得花心思。先跑通最小可用版本再补线程池、重试、记录表最后再把模板规范起来这套流程走下来基本不会再出大问题。希望这篇能帮你把 SpringBoot 邮件发送这块一次搞定。
SpringBoot邮件发送全攻略：从基础配置到异步化与避坑指南
SpringBoot整合邮件发送这事我前后在好几个项目里都搭过从最开始用原生 JavaMail API 手写工具类到后来换成spring-boot-starter-mail全家桶踩过的坑确实不少。最典型的一个是刚上手时配置文件里的主机端口对着网上抄结果发不出去连个像样的报错都没有后来开了 debug 日志才看到是加密协商方式不对。这篇就把 SpringBoot 整合 Email 邮件发送这套完整捋一遍从环境准备、配置项拆解、纯文本/HTML/附件/模板邮件写法到异步化处理和疑难问题排查全部给到你无论你是刚接触 SpringBoot 的新人还是想系统梳理邮件这块的老手都能直接拿来用。1. 项目整体思路与方案选型1.1 需求场景分析邮件发送在真实项目里几乎是刚需。注册验证码、密码找回、订单状态变更提醒、定时报表推送、告警通知这些场景都会走到发邮件这一步。不同场景对邮件功能的要求差别很大验证码、通知类纯文本或简单 HTML 就行要求发送速度快、不能阻塞主业务流程。营销、报表类需要模板渲染带着图片、附件内容要漂亮发送量大。告警类对可靠性要求高发送失败要有重试和补偿机制。所以在动手写代码之前先想清楚自己到底要做哪种这会直接影响后面是选SimpleMailMessage还是MimeMessageHelper要不要上消息队列要不要做重试。1.2 邮件协议基础SMTP、POP3、IMAP邮件发送最常见的协议是 SMTPSimple Mail Transfer Protocol负责把邮件从客户端送到邮件服务器再由服务器转发到对方的邮箱。SpringBoot 整合 Email 时JavaMailSender底层就是在跟 SMTP 服务器打交道。POP3 和 IMAP 是收件协议发邮件的时候基本用不到。但有一个点很关键很多邮箱服务商比如 QQ 邮箱、163 邮箱默认关闭了 SMTP 服务你需要在邮箱设置里手动开启 SMTP 服务并获取一个“授权码”用它代替登录密码来完成认证。这个授权码不是你的邮箱密码是服务商单独生成的一串口令专门给第三方客户端用。关于端口有个容易出错的地方常见的 SMTP 端口是 25、465、587。25 端口是传统 SMTP 端口很多云厂商默认封禁465 是 SSL 加密端口587 是 STARTTLS 加密端口。SpringBoot 配置里如果写 465通常需要配上mail.smtp.ssl.enabletrue这类参数写 587 则要开启STARTTLS混着用就会连不上或者认证失败。具体用哪个以邮箱服务商文档为准。1.3 选型对比spring-boot-starter-mail 为什么是首选市面上做邮件发送的 Java 方案不少直接用javax.mailJavaMail API、spring-boot-starter-mail、Apache Commons Email、jmail 等第三方组件还有各种云厂商的邮件推送服务。spring-boot-starter-mail是 Spring Boot 官方提供的封装底层还是 JavaMail但它做了大量自动配置和封装把复杂细节吞掉了。比如你只要在application.yml里配好spring.mail相关属性Spring Boot 会自动创建JavaMailSenderImpl这个 Bean直接注入到你的业务代码里就能用不需要手动创建 Session、配置 Store 之类的对象。相对 jmail 这类组件它的优势是跟 Spring 生态无缝集成支持Async、支持MimeMessageHelper这种丰富的消息构造工具社区资料也多。如果是特别大规模、对送达率要求极高的营销邮件建议用云厂商的邮件推送服务但绝大多数业务系统内部的通知、验证码、报表邮件spring-boot-starter-mail完全够用代码干净、维护成本低。2. 环境准备与基础配置2.1 依赖引入与版本选择在pom.xml里加依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-mail/artifactId /dependency不需要手动写版本号SpringBoot 父工程已经管理了版本。我用的是 SpringBoot 2.7.x 和 3.x 都可以代码写法基本一致。唯一要注意的是 SpringBoot 3.x 里 JavaMail 使用的包名从javax.mail变成了jakarta.mail不过只要用 Spring 封装好的JavaMailSender和MimeMessageHelper这个问题基本感知不到底层已经帮你处理了。如果你的项目还要用 Thymeleaf 渲染模板邮件额外加一个依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency2.2 application.yml 配置参数逐项拆解拿 QQ 邮箱举例最小可用的配置长这样spring: mail: host: smtp.qq.com port: 465 username: your_accountqq.com password: your_auth_code protocol: smtp properties: mail: smtp: auth: true ssl: enable: true socketFactory: class: javax.net.ssl.SSLSocketFactory这里每个参数我都说一下我的理解spring.mail.hostSMTP 服务器地址。QQ 邮箱是smtp.qq.com163 是smtp.163.com企业微信邮箱是smtp.exmail.qq.com阿里企业邮箱是smtp.qiye.aliyun.com。spring.mail.port加密端口。QQ 邮箱和 163 都支持 465SSL和 587STARTTLS我习惯用 465。spring.mail.username发件邮箱完整地址。spring.mail.password这里填的不是邮箱登录密码是授权码。很多人卡在这一步后面单独说。spring.mail.protocol默认就是smtp可以不写。properties.mail.smtp.auth是否开启 SMTP 认证必须为true。properties.mail.smtp.ssl.enable和socketFactory.class465 端口下开启 SSL 加密。有些服务商要求必须指定SSLSocketFactory否则会报Could not convert socket to TLS之类的错误。另外有一个调试利器建议加上spring: mail: properties: mail: debug: true开启后控制台会打印完整的 SMTP 协议交互过程包括客户端和服务器之间的EHLO、AUTH LOGIN、MAIL FROM、RCPT TO、DATA等指令。排查连接不上、认证失败问题时非常有用定位完再关掉就行。2.3 授权码的获取与配置安全以 QQ 邮箱为例登录网页版 QQ 邮箱进入“设置” - “账户”找到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”开启“SMTP服务”这时候会要求发送一条短信验证验证通过后会给出一串授权码复制保存下来填到配置里注意不要用邮箱的登录密码。163 邮箱类似在“设置” - “POP3/SMTP/IMAP”里开启服务设置客户端授权密码。企业邮箱一般需要管理员在后台开启“SMTP 服务”并生成专属密码或授权码。有几个安全细节值得注意授权码相当于邮箱的“半把钥匙”不要提交到 Git 仓库。我一般会把配置外置到application-prod.yml或者用环境变量加载password: ${MAIL_PASSWORD}。不要把授权码硬编码在代码里更不要打印在日志中。如果公司有配置中心Nacos、Apollo 等建议把邮件配置放配置中心管理方便动态调整也避免密钥泄露。3. 核心功能实现从纯文本到模板附件3.1 最简单的纯文本邮件先创建一个邮件服务类核心就是注入JavaMailSender然后构造SimpleMailMessageService public class MailService { private final JavaMailSender mailSender; public MailService(JavaMailSender mailSender) { this.mailSender mailSender; } public void sendSimpleMail(String to, String subject, String text) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(your_accountqq.com); message.setTo(to); message.setSubject(subject); message.setText(text); mailSender.send(message); } }setFrom这里有个坑有些邮箱服务商要求发件人地址必须跟配置里的spring.mail.username一致否则会报553 Mail from must equal authorized user错误。如果你确实想用别的显示名称可以用这种写法message.setFrom(your_accountqq.com);或者如果你用的是 JavaMailSenderImpl 的MimeMessageHelper可以这样helper.setFrom(your_accountqq.com, 技术小站);指定了发件人姓名后对方收件箱里显示的就是“技术小站”而不是冷冰冰的邮箱地址。调用方式很简单在业务代码里注入MailService直接调sendSimpleMail(someoneexample.com, 测试主题, 测试内容)即可。但我这里提个醒这个写法是同步的如果邮件服务响应慢你的接口就会跟着变慢后面 3.4 节会讲怎么改造成异步。3.2 HTML 邮件与模板渲染纯文本邮件能解决“能发”的问题但要发漂亮的营销邮件、报表就得用 HTML。Spring 提供了MimeMessageHelper用起来也简单public void sendHtmlMail(String to, String subject, String html, String fromName) { try { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_accountqq.com, fromName); helper.setTo(to); helper.setSubject(subject); helper.setText(html, true); mailSender.send(message); } catch (MessagingException | UnsupportedEncodingException e) { log.error(发送HTML邮件失败, e); throw new RuntimeException(e); } }注意两点new MimeMessageHelper(message, true, UTF-8)第二个参数true表示 multipart 模式支持附件和内嵌资源第三个参数指定编码为 UTF-8避免中文乱码。实际项目里我基本不会在代码里拼 HTML 字符串那样维护性太差改用模板引擎。最常见的组合是 SpringBoot ThymeleafService public class TemplateMailService { private final JavaMailSender mailSender; private final SpringTemplateEngine templateEngine; // 构造器注入省略 public void sendTemplateMail(String to, String subject, MapString, Object params) { Context context new Context(); context.setVariables(params); String content templateEngine.process(mail/order-notify.html, context); try { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_accountqq.com, 商城系统); helper.setTo(to); helper.setSubject(subject); helper.setText(content, true); mailSender.send(message); } catch (MessagingException | UnsupportedEncodingException e) { log.error(发送模板邮件失败, e); throw new RuntimeException(e); } } }对应的模板文件src/main/resources/templates/mail/order-notify.html!DOCTYPE html html langzh xmlns:thhttp://www.thymeleaf.org body h3 th:text你好 ${userName} 你好用户/h3 p您的订单 span th:text${orderNo}202501010001/span 已发货请注意查收。/p /body /html参数通过Map传进去模板里用${}占位。这样做的好处是前端同学可以独立调整邮件样式不会影响后端逻辑。我还试过用 Freemarker 替代 Thymeleaf原理类似选哪个看你项目里已有的技术栈别单独为了邮件再引入一套。3.3 附件与内嵌图片邮件带附件的邮件要用到MimeMessageHelper.addAttachment方法public void sendAttachmentMail(String to, String subject, String content, File attachment) { try { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(your_accountqq.com); helper.setTo(to); helper.setSubject(subject); helper.setText(content); // 添加附件 helper.addAttachment(MimeUtility.encodeText(attachment.getName()), attachment); mailSender.send(message); } catch (MessagingException | UnsupportedEncodingException e) { log.error(发送附件邮件失败, e); } }上面代码里我用了MimeUtility.encodeText(attachment.getName())这一步很关键。如果你直接helper.addAttachment(attachment.getName(), attachment)中文文件名在部分邮箱客户端里会显示成乱码。用MimeUtility.encodeText对文件名进行 RFC 2047 编码后绝大多数客户端都能正确显示中文附件名。内嵌图片是另一种场景比如邮件里直接显示一张带二维码的图片而不是附件。做法是用addInlinehelper.setText(htmlbody请扫描二维码img srccid:qrCode//body/html, true); ClassPathResource resource new ClassPathResource(static/qrcode.png); helper.addInline(qrCode, resource);注意 HTML 里要用cid:qrCode引用图片addInline的第一个参数跟cid后面的名字保持一致。图片会作为邮件内嵌资源发送而不是附件下载。附件大小要留意普通邮箱服务器一般限制单个邮件总大小在 20MB 到 50MB 不等超出会被服务器拒绝。如果业务上有大文件附件需求建议先传对象存储OSS/COS然后在邮件里放下载链接别直接塞附件。3.4 异步化改造别让邮件拖垮接口邮件发送涉及网络 IO如果同步执行请求方会一直等到邮件服务器响应才返回。注册接口里如果同步发验证码用户体验会非常差。解决办法就是异步化。SpringBoot 里最简单的方式是加Async注解。先开启异步支持Configuration EnableAsync public class AsyncConfig { Bean(mailExecutor) public Executor mailExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(5); executor.setQueueCapacity(100); executor.setThreadNamePrefix(mail-thread-); executor.initialize(); return executor; } }然后在发邮件的方法上指定线程池Async(mailExecutor) Override public void sendSimpleMail(String to, String subject, String text) { // 实际发送逻辑 }需要注意两点Async生效的前提是方法被 Spring 代理调用所以不能同类内部调用也就是说你不能在同一个类里写完一个普通方法又直接调另一个带Async的方法另外异步方法里如果抛异常调用方式是感知不到的所以建议在方法内部捕获异常做好日志和补偿记录。做异步之后要思考一个问题如果发送失败怎么办我的做法是给异步方法加一个发送失败的重试机制最简单的方式是用Retryable或在方法内部手动捕获异常并按次数重试。更稳妥一点可以把发送任务落到数据库做成一张mail_send_record表记录收件人、主题、内容、发送状态和重试次数由定时任务扫描失败的记录重新发送。这样才能保证业务系统不发漏邮件。4. 常见问题、避坑经验与高频面试考点4.1 高频报错速查表邮件发送的问题一般不难定位难的是你连报错都不看就瞎试。我把自己实测过的报错整理成了表格给新手朋友当个对照表用报错信息原因解决办法AuthenticationFailedException用户名或授权码错误检查spring.mail.password是否为授权码不是登录密码SocketException: Connection reset端口和加密方式不匹配465 端口配 SSL587 端口配 STARTTLSMessagingException: Unknown SMTP hosthost 配置错误确认邮箱服务商 SMTP 地址是否写对MailSendException: Couldnt connect to host网络不通或端口被封检查防火墙、云厂商安全组是否放行对应端口553 Mail from must equal authorized user发件人与认证用户不一致setFrom地址必须跟spring.mail.username一致501 Syntax error in parameters or arguments邮件地址格式错误检查收件人地址是否为空、格式是否正确Invalid Addresses收件人地址非法检查setTo传的是不是邮箱地址多个用逗号分隔这里特别提醒一点看到MailSendException不要慌先开spring.mail.properties.mail.debugtrue看协议日志里具体是哪一步失败。常见的是在AUTH LOGIN之后就断了那就一定是认证问题如果卡在MAIL FROM或RCPT TO那基本是校验失败比如发件人不一致或收件人格式不对。协议日志会把问题展示得明明白白。4.2 那些年我踩过的邮件坑聊几个平时文档里不会写那么细的坑都是我实际碰到过的。第一个坑是只有一个收件人的时候用setTo(String)多个收件人用setTo(String...)但如果你不小心传了一个空字符串进去就会报 Invalid Addresses。而且这个报错有时候不会立刻暴露邮件服务器那边可能在 DATA 阶段才拒绝排查起来很绕。我的习惯是封装一个校验方法在调用mailSender.send之前先检查一下收件人列表是否为空这个检查成本极低收益却很明显。第二个坑是启动时如果配置不对SpringBoot 项目并不会启动失败而是等你真正调用send方法时才抛异常。这就导致很多人以为自己配置好了结果上线接口一调就炸。应对办法是加一个启动检查的ApplicationRunner项目启动时用配置的发件人给自己发一封测试邮件发不出去就启动失败把问题挡在测试环境。第三个坑是高并发下的连接池问题。JavaMailSenderImpl默认不会复用连接每次发送都建立新的 SMTP 连接如果发信量大会频繁建连、断连性能很差。可以配置连接池比如在spring.mail.properties里设置mail.smtp.connectiontimeout和mail.smtp.timeout或者使用 Commons Pool 复用Transport连接。不过绝大多数业务系统的发信量到不了这一步如果真到这一步建议直接换成云邮件推送服务省心得多。第四个坑是附件名和文件名中文乱码问题。有的同学配置了 UTF-8 编码正文显示没问题但附件名还是乱码原因就在addAttachment传原始文件名时没有做 RFC 2047 编码。这个问题在不同邮箱客户端显示不一致Outlook 和 Gmail 的处理方式还不一样保险起见统一用MimeUtility.encodeText处理。第五个坑是发送频率限制。无论是 QQ 邮箱还是 163 邮箱日常账号都有每天发信量上限一般在每天几百封到上千封不等。如果你的业务是群发营销邮件用普通邮箱账号发很容易触发风控轻则进垃圾箱重则封禁 SMTP 功能。这种场景必须用企业邮箱或云邮件推送服务来解决。4.3 顺带聊聊 SpringBoot 邮件相关的面试考点热词里出现了“springboot面试题”我猜有不少读者其实是在准备面试。邮件发送这个功能虽然简单但面试官特别喜欢从里面挖几个点第一个问题是“SpringBoot 的邮件自动配置是怎么做到的”。答案核心是MailSenderAutoConfiguration。它在classpath存在javax.mail.internet.MimeMessage并且容器里没有JavaMailSenderBean 时会根据spring.mail前缀的属性创建JavaMailSenderImpl。这就是为什么你只加一个依赖、写几行配置就能注入JavaMailSender。第二个问题是“JavaMailSender和JavaMailSenderImpl的区别”。JavaMailSender是接口JavaMailSenderImpl是它的实现类。平时注入接口就行但如果你想在运行时动态修改配置比如同一个系统要切换不同发件人可以拿到JavaMailSenderImpl实例调用setUsername、setPassword动态修改。第三个问题是“如何确保邮件不丢失”。这个问题没有标准答案但能考察系统设计能力。基本的思路是发送任务持久化到数据库设置状态字段发送成功后更新状态发送失败记录错误原因并定时补偿。更进阶的方案是用 MQ 削峰把发送请求异步写入队列消费者慢慢处理再配合失败重试和告警。第四个问题是“MimeMessageHelper为什么必须指定 UTF-8”。因为邮件消息的编码规则比较复杂如果不显式指定 charset可能使用平台默认编码遇到中文内容就会乱码。指定 UTF-8 是跨平台、跨邮件客户端最稳妥的做法。第五个问题是“多个收件人如何做到互相不可见”。互不可见要用密送setBcc而不是setCc。面试官可能会追问两者差别Cc抄送的收件人能看到其他收件人地址Bcc密送的收件人看不到其他收件人地址适合群发场景能保护用户隐私。这些考点本身不难但能把自动配置原理和异常处理机制聊清楚的人确实不多你如果能把实际踩坑的经验一起讲出来面试官会高看你一眼。我自己的经验是邮件功能看着简单真正要做到稳、快、不丢还是得花心思。先跑通最小可用版本再补线程池、重试、记录表最后再把模板规范起来这套流程走下来基本不会再出大问题。希望这篇能帮你把 SpringBoot 邮件发送这块一次搞定。 
