Spring Boot 发送 QQ 邮箱邮件从 530/535 错误到成功发送的全踩坑指南先说说我为什么写这篇。前阵子给一个项目加用户注册后的邮件验证码通知功能技术栈就是 Spring Boot邮箱选的 QQ 邮箱——因为项目方要求必须用 QQ 邮箱作为发件账号说是他们公司统一的企业邮箱流程还没走完先拿个人 QQ 邮箱顶上。我原本以为这事很简单Spring Boot 对邮件的支持非常成熟spring-boot-starter-mail一引application.yml里配几行JavaMailSender 直接用就完事了。结果从开始配到真正跑通整整折腾了一天半中间反复被 530 和 535 这两个错误码教做人。网上资料倒是不少但要么是零散的片段要么是直接把官方文档翻译一遍没有一个帖子能让我按着走完一遍不掉坑的。所以我把完整过程、错误码的底层含义、每一步的排查思路以及最终能直接照抄的配置方案全部整理出来。这篇文章不打算讲什么高深原理就当作一个踩坑记录和排查手册给后面接手同类需求的同学省点时间。1. 项目背景与核心需求拆解1.1 当时项目里为什么要发邮件那个阶段的项目是一个面向 C 端的 Web 服务用户注册需要绑定邮箱登录时支持邮箱验证码代替密码登录。在设计里邮箱验证码这一环承担了两个职能一是确认用户填写的邮箱确实是他本人的二是作为低安全级别操作的身份凭证。开发周期很紧没有单独搭消息中心服务的余裕所以邮件发送功能直接落在业务服务里走最朴素的方案——Spring Boot 内嵌的邮件发送能力。后期如果邮件发送量大了再拆出去也不迟接口层面先做好隔离就行。这种场景在中小型项目里非常典型。不需要上什么企业级的邮件推送平台也不需要搞复杂的消息队列异步化只要在业务代码里提供一个发邮件的 Service谁需要发邮件谁调一下就完事了。1.2 为什么发件账号选了 QQ 邮箱这个其实没有什么技术层面的考量和纠结纯粹是业务要求。但事后复盘QQ 邮箱作为发件方有一个不得不注意的技术特点它对第三方客户端的 SMTP 登录做了非常严格的安全限制必须使用授权码而不是登录密码必须走 SSL 加密连接。这两条限制恰好是后面所有坑的根源。因为 QQ 邮箱的这些限制导致网上 90% 的邮件发送相关教程只要是拿 QQ 邮箱做演示的几乎都有踩坑记录。反过来想只要把 QQ 邮箱这条路趟平了后面换任何一家邮箱服务商的 SMTP 都是降维操作原理完全一样无非改几个配置项。1.3 技术栈和版本说明我用的版本组合如下不同版本之间差异不大但为了后面照着配置不出偏差还是先列一下Spring Boot 2.7.xspring-boot-starter-mailJDK 1.8Maven 构建为什么特意提 JDK 版本因为 Spring Boot 2.7 在 JDK 8 下的行为跟在 JDK 11、17 下有些细微差别尤其是 SSL 相关的一些默认行为。我用 JDK 8 跑通了之后又在 JDK 11 环境里试了一遍发现只要配置方式一致结论是一样的。所以版本影响不大关键是配置项别搞错。2. 准备工作把 SMTP 服务先开通2.1 QQ 邮箱的 SMTP 服务必须在网页端开启很多人第一次搞这个上来就去改代码配置写完之后跑一下报错然后开始怀疑人生。实际上有个前置步骤漏了QQ 邮箱的 SMTP 服务默认是关闭的你不去网页端手动打开后面写什么都白搭。操作路径是登录 QQ 邮箱网页版 → 设置 → 账户 → 往下翻找到POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务这一栏 → 把 SMTP 服务的开关打开。打开的过程中会要求用手机发一条短信验证这是腾讯安全策略的一部分挺正常照着走就行。关键点来了开启 SMTP 服务之后会给你一串授权码记住这个授权码因为这就是你后面在代码里用来当密码的东西。QQ 邮箱的密码在这里是无效的只认授权码。我当时没仔细看提示拿着登录密码配了一把被 535 错误虐了半小时才反应过来。提示授权码只在第一次生成时完整显示后面再进到这个页面只会看到一串星号。如果你把授权码弄丢了只能删除后重新生成一个旧授权码立即失效。所以生成之后第一时间存好。2.2 搞清楚 SMTP 服务器地址和端口QQ 邮箱的 SMTP 配置信息是这样服务器地址是smtp.qq.comSSL 端口是465非 SSL 端口是25。这里建议直接用 465 加 SSL 的方式别去折腾 25 端口。25 端口在很多云服务商的网络环境里是被默认封禁的因为你买的服务器可能本身就部署了大量邮件服务运营商出于反垃圾邮件的考虑普遍把 25 端口直接禁掉。你可能在网上看到有人说用smtp.qq.com:587配合 STARTTLS 也能行这个对 QQ 邮箱来说不是最优解QQ 邮箱的 587 端口虽然开放但对 JavaMail 的兼容性不如 465 那么稳。我在实际测试中用 587 端口能通但第一次握手时如果 SSL 参数没配对很容易触发 530 错误。综合来看465 SSL 是最省心的组合。2.3 验证网络连通性在写任何代码之前先在命令行里验证一下你的服务器能不能连上smtp.qq.com的 465 端口。这一步能帮你把网络不通和代码错误这两个问题隔离开来。telnet smtp.qq.com 465如果 telnet 提示连接失败大概率是网络层面的问题先查防火墙、安全组策略或者干脆换一台网络环境干净的服务器再试。如果连接成功会进入一个黑窗口随便敲几个字母再关掉就行这个阶段不需要发什么命令能连上就说明网络畅通。这一步别跳过。我见过一些同事代码配了半天发现发不出去最后排查来排查去是测试环境服务器的 465 端口压根没放通。这个坑在本地开发时很少出现但在云服务器上太常见了。3. 第一个坑实录530 错误到底在说什么3.1 530 报错的现象我最初的配置是这样的spring: mail: host: smtp.qq.com port: 465 username: xxxqq.com password: xxxxxxxx代码就是一个很普通的发送逻辑Service public class MailService { Autowired private JavaMailSender mailSender; public void sendSimpleMail(String to, String subject, String content) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(xxxqq.com); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); } }跑起来之后异常日志里出现了这样一段com.sun.mail.util.MailConnectException: Couldnt connect to host, port: smtp.qq.com, 465; Caused by: javax.net.ssl.SSLException: Connection reset或者在某些情况下是Exception in thread main com.sun.mail.util.MailConnectException: Couldnt connect to host, hostsmtp.qq.com, port465当时一看到 SSLException 和 Connection reset我的第一反应是网络问题怀疑是不是 465 端口被封了。可是前面明明刚用 telnet 验证过端口是通的。那就很奇怪了端口通但握手失败问题肯定出在 SSL 层。3.2 网上搜到的答案和实际的原因遇到这个问题后我搜了一圈网上讨论最多的一个说法是缺了这样一段配置spring: mail: properties: mail: smtp: ssl: enable: true当时我确实没写这段。为什么没写因为我以为port: 465本身就暗示了走 SSL——毕竟 465 的全名就是SMTP over SSL的端口。但 JavaMailSender 的默认行为并不会因为你写了 465 就自动启用 SSL它需要显式声明mail.smtp.ssl.enabletrue才真的走 SSL 通道。这里需要展开讲讲原理。邮政模块底层用的是 JavaMail即 Jakarta MailJavaMail 在建立连接时默认认为你使用的是纯文本的 SMTP 协议。端口号是 465 也好是 25 也好对 JavaMail 来说只是连哪个端口的问题不代表它要自动升级到 SSL。所以你必须告诉它这个端口上的连接要用 SSL 加密。加了这段配置之后连接阶段算是过去了。但你以为这就完了并没有第二个坑马上接踵而至。3.3 SSL 配置正确后的 530 变体还有一种 530 错误长这样Caused by: javax.mail.AuthenticationFailedException: 530 5.7.1 Must issue a STARTTLS command first. y8sm8061678pfg.271 - gsmtp这个现象我后面模拟过发生在你用的是 STARTTLS 方式587端口但没有正确发送 STARTTLS 指令时。QQ 邮箱那边收到明文指令就不干了直接告诉你必须先走 STARTTLS。如果你走的是 465 SSL 路径理论上不会出现这个具体报错。但如果你的请求先尝试了 STARTTLS 失败又回退到非加密模式JavaMail 有时候会在日志里打印出类似 530 的内容很容易让人绕晕。所以这里有个经验原则选定一条加密路径就走到底不要混合着用。注意530 错误的本质是加密协商未完成而不是账号密码错误。遇到这种报错优先检查 SSL 是否显式启用其次检查端口是否匹配加密方式最后再看账号密码。4. 第二个坑实录535 错误的来龙去脉4.1 535 报错的完整日志SSL 配置对之后再次运行程序日志里弹出了新的错误码javax.mail.AuthenticationFailedException: 535 5.7.8 Username and password not accepted. y8sm8061678pfg.271 - gsmtp看到 Username and password not accepted 这个措辞你很容易联想到账号密码错了。我当时第一反应也是是不是用户名写错了是不是密码复制漏了字符然后我把用户名和密码反反复复检查了好几遍甚至换个平台重新复制了一次密码还是报同样的错误。后来才意识到这个密码根本不是邮箱登录密码而是授权码。我把邮箱的登录密码填进去了服务端当然拒绝。4.2 密码和授权码的区别是什么QQ 邮箱的授权码相当于一个为第三方客户端单独生成的专用密码它的权限范围其实也挺大——能操作你的邮件收发。但是好处是它跟登录主密码是独立的你可以在任何设备上单独吊销授权码而不用改主密码防止其他客户端被连带踢下线。所有支持 SMTP 的国内主流邮箱服务商都有类似的机制。QQ 邮箱生成授权码的过程在 2.1 里写过了不再重复。核心记住一句话代码里的 password 字段填的是授权码不是 QQ 密码。提示如果在网页端重新生成了授权码旧的授权码立即失效。如果代码里配置的授权码是旧的下次发送就会立刻被打回 535 错误。排查的时候如果之前好好的、突然开始报 535优先回想一下是不是最近重置过授权码。4.3 535 错误的另一种可能账号书写格式还有一个容易被忽视的细节用户名要写完整的邮箱地址比如someoneqq.com不能只写someone。有些邮箱服务商支持只写账号前缀但 QQ 邮箱严格要求全地址格式。这个在报错信息里不容易看出来因为服务端只会告诉你 auth 失败不告诉你具体是格式问题还是值的问题。所以排查 535 时检查清单里加上一条用户名是不是完整邮箱格式。把这几个点都走通之后程序终于不再报错了我一封测试邮件顺利发送成功。但整个项目里邮件发送功能不能只跑通一个最简单的场景后面还有更多细节要处理。5. 完整可复用的邮件发送封装5.1 配置文件的最终形态下面直接给出我验证过可以稳定运行的完整配置复制过去改掉账号和授权码就能用spring: mail: host: smtp.qq.com port: 465 username: yournameqq.com password: 你的授权码 default-encoding: UTF-8 properties: mail: smtp: socketFactory: class: javax.net.ssl.SSLSocketFactory ssl: enable: true auth: true starttls: enable: false这里有三个配置项值得单独说明一下smtp.authtrue表示 SMTP 连接需要进行身份认证。不写的话JavaMail 默认确实是不开启认证的那服务端连接过来之后不送账号密码直接被拒。Spring Boot 的spring.mail.username/password配置虽然提供了值但底层 JavaMail 是否启用了 AUTH 指令需要看这个auth参数。实际测试中发现有些版本不写也自动带上但显式声明更稳妥。socketFactory.class指定使用javax.net.ssl.SSLSocketFactory来创建套接字。这相当于显式告诉 JavaMail所有通信都要经过 SSL 套接字。这个配置和mail.smtp.ssl.enabletrue的作用有重叠本质上都指向启用 SSL区别在于前者更偏底层兼容性更好。starttls.enablefalse明确关闭 STARTTLS。因为走的是 465 端口直连 SSL不需要 STARTTLS 这一层关了反而干净避免 JavaMail 在某些情况下优先尝试 STARTTLS 引发 530 变体。5.2 JavaMailSender 封装代码最终我在项目里保留了一个偏向业务的 Service。底层 Spring 已经帮我们把JavaMailSender接口实现好了直接用就行。为了提高复用性我封装了三个方法纯文本、富文本 HTML、带附件。下面贴出核心代码。首先是纯文本邮件适合验证码、通知类简单场景Service public class MailService { Value(${spring.mail.username}) private String from; Autowired private JavaMailSender mailSender; public void sendSimpleMail(String to, String subject, String content) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(from); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); } }这里from直接取配置文件里的 username避免在代码里硬编码邮箱地址。有一个细节setFrom如果跟配置的 username 不一致部分邮箱服务商可能会拒绝发送。QQ 邮箱对发件人地址的校验比较严格最好保持一致。5.3 富文本 HTML 邮件验证码邮件虽然简单但业务里往往还涉及营销通知、欢迎邮件这类更需要样式的场景。这种邮件建议直接用 HTML 格式发送SimpleMailMessage就不够用了改用MimeMessagepublic void sendHtmlMail(String to, String subject, String htmlContent) throws MessagingException { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(from); helper.setTo(to); helper.setSubject(subject); helper.setText(htmlContent, true); mailSender.send(message); }MimeMessageHelper的第二个参数true表示启用 multipart 模式这样邮件正文可以携带内嵌资源和附件。第三个参数指定字符集为 UTF-8这一步非常重要不然 HTML 内容里的中文在客户端显示时会变成乱码。helper.setText(htmlContent, true)里的第二个参数true就是告诉 JavaMail 这段文本是 HTML 而不是纯文本。很多人漏了这个参数结果发出去的邮件显示的是源代码一长串div标签直接码在内容区特别尴尬。5.4 带附件的邮件业务里涉及导出报表、合同文件之类的场景就需要附件能力。代码如下public void sendAttachmentMail(String to, String subject, String text, File attachment) throws MessagingException, IOException { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(from); helper.setTo(to); helper.setSubject(subject); helper.setText(text, false); helper.addAttachment(attachment.getName(), attachment); mailSender.send(message); }addAttachment支持传入File、InputStreamSource等类型。如果你是从内存里生成的文件比如 Excel 导出流用ByteArrayResource或者InputStreamResource包一下再传进去这样避免先把临时文件写到磁盘上的额外开销。5.5 解决 mailsender 自动装配的问题某个同事在照着我这个方案配置时遇到一个怪问题Autowired private JavaMailSender mailSender;这一行报错提示没有JavaMailSender类型的 Bean。明明依赖加了吗加了。配置配了吗配了。后来发现他的类被放在了启动类能扫描到的包外面Spring 没有扫描到所以那些自动配置类生成的 Bean 也注入不进去。这不是邮件模块特有的问题是 Spring Boot 包扫描的基本边界问题。把类移到启动类同级或子包内就解决了。另一个场景是项目里有多套邮件配置可能会注入多个JavaMailSender实例。这种场景下用Qualifier或者按配置中心设定来区分 Bean就属于进阶玩法了这里不展开。6. 常见问题与排查技巧实录6.1 错误速查表下面这张表是根据我实际踩过的、以及帮同事排查过的各种问题整理而来。以后遇到同类报错先对照这个表定位方向报错现象常见原因排查步骤MailConnectException: Connection resetSSL 未显式启用检查 ssl.enable 和 socketFactory.class 配置530 5.7.1 Must issue a STARTTLS command firstSSL/STARTTLS 方式混用确认端口和加密方式一致性465 就走纯 SSL535 5.7.8 Username and password not accepted授权码错误或使用了登录密码重新生成授权码确认 password 字段用的是授权码535 5.7.0 Must issue a STARTTLS command first465 端口配了 starttls.enabletrue将 starttls.enable 设为 false454 4.7.0 Temporary authentication failure服务器时间偏差或 IP 信誉问题校准服务器时间更换发件 IP 测试连接 25 端口超时云服务商封禁 25 端口换 465 端口走 SSL6.2 发件人显示名称的问题纯文本邮件默认发件人显示的是邮箱地址邮件的发件人一栏会显示xxxqq.com很不美观。想显示成某某系统这样的名称在 MimeMessageHelper 里用这样写helper.setFrom(from, 某某系统);原理是利用了 MIME 协议里发件人字段的编码格式把显示名称和地址拼在了一起。国内大厂的邮箱客户端对中文发件人名称的支持都很好可以放心用。6.3 异步发送的必要性在业务里直接同步发送邮件有一个隐患如果 SMTP 服务端响应慢当前线程就会被阻塞用户那边表现为接口迟迟不返回。更糟糕的情况是SMTP 服务端临时不可用mailSender.send()抛出异常直接导致整个业务操作失败——用户本来只是注册个账号结果因为邮件服务不可用注册请求也跟着失败。所以生产环境里一定把邮件发送放到异步线程池里去。Spring 自带Async注解配一个线程池就能用。不过要注意异常处理异步方法里的异常不会抛给调用方要在方法内部捕获处理记录日志否则邮件发送失败时会静默丢失。6.4 我在重试策略上的配置心得生产环境的邮件发送我习惯加上重试机制。这个重试不是说代码里自己写个 for 循环而是让消息先落到本地表或者消息队列里。一个简单的设计是建一张邮件发送记录表状态字段记录待发送、已发送、发送失败。定时任务扫描发送失败且重试次数未到上限的记录再次触发发送。这样做的收益非常直接即便 SMTP 服务商临时故障消息不会丢等故障恢复后定时任务会自动把积压的邮件发出去。我在那个项目里就用了这个方案上线之后邮件发送的成功率几乎到了 99.9%剩下的那 0.1% 是用户的邮箱地址本身写错了。6.5 邮件正文中的图片处理邮件正文如果要带图片有两种方式一种是图片放到图床/CDN正文里用img srchttps://...引用另一种是把图片作为内嵌资源放进邮件里。前者实现简单但有些邮箱客户端在加载远程图片时会要求用户手动点一下显示图片体验打折。后者更稳妥相当于把图片塞进了邮件本体打开就能看到。内嵌实现方式是在MimeMessageHelper中调用addInlinehelper.addInline(logo, new ClassPathResource(logo.png));然后在 HTML 里通过cid:logo来引用img srccid:logo用了addInline之后邮件整体体积会变大但这类内嵌资源通常是几十 KB 级别的 logo 或小图在可接受范围内。如果非要附带几 MB 的高清图那建议还是放图床不然用户体验会很差。6.6 关于测试环境的实测结论在本地开发环境里我第一次成功发送邮件后又在测试环境跑了一轮。测试环境的服务器是某云厂商的轻量级服务器安全组策略默认只放行 80/443/22 等常见端口465 端口初始是封着的。同样一段代码本地 OK上了测试环境就超时。这个差异让我当时一度以为是代码移库时装坏了什么东西实际上是云厂商安全组的惯性判断。所以如果你是在云服务器上部署项目除了代码之外一定记得打开安全组规则里对应 SMTP 端口的出站方向访问权限。虽然大多数云平台对出站方向限制较少但少数平台在轻量应用服务器上做了额外限制这个东西在控制台里就能设置不需要提交工单。6.7 授权码泄露的应对授权码本质上就是密码级别的机密信息如果写在了代码仓库里那就等于把邮件账号拱手让人。为了避免这个问题配置里不要硬编码授权码改成环境变量注入spring: mail: password: ${MAIL_AUTH_CODE}然后在服务器或者 CI/CD 工具中配置MAIL_AUTH_CODE这个环境变量。这样即使代码不小心被推到公开仓库授权码也不会暴露。如果不幸授权码还是泄露了第一时间登录 QQ 邮箱网页端在设置里删除旧的授权码并重新生成把泄露的凭证作废掉不要抱着应该没事吧的侥幸心理。重置之后代码里的配置也要同步更新到位不然下次发送又是一记 535。7. 从这次踩坑里总结出的通用经验走完这一趟我对邮件发送这件事的复杂度有了新的认识表面上看它就是往配置里填几行参数的事实际上每一步都藏着影响成败的暗桩。先说说我对这些报错码的新理解。530 并不是世界末日它本质上是在提醒你SSL/STARTTLS 这层加密没谈拢。排查它的时候脑子里要先有一个清晰的链路图Socket 建立 → 加密协商 → 身份认证 → 邮件指令 → 退出登录。530 发生在加密协商阶段535 发生在身份认证阶段阶段不同排查方向完全不同。其次是配置中心化的重要性。一个小项目可以接受把配置直接写在 yml 里但只要项目规模上来多环境、多项目复用邮件配置散落在各处就是噩梦。我现在更倾向于把邮件配置单独用一个配置类管理代码里只面向接口编程具体用哪家邮箱服务商、哪个发件账号由环境决定。还有一点是日志的重要性和敏感性。JavaMail 可以开启调试模式打印出跟 SMTP 服务器交互的完整明文对话。这个模式在排查问题时非常好用能直观看到客户端和服务端每一步的往来。但也正因为它是明文的调试日志里会带着授权码信息线上环境绝不可能随意开着。我当时在本地开了调试模式定位完问题就立刻关掉了。调试模式的开启方式spring: mail: properties: mail: debug: true输出的日志会包含DEBUG SMTP: connected to host...、DEBUG SMTP: AUTH command failed这类信息对定位问题很有帮助。这次的经历也让我养成了一个习惯但凡用邮件服务先写一段基于 JavaMail 的探针代码把连接、认证、发信这几个环节拆开单独验证哪个环节挂了一目了然。不要直接用 Spring Boot 包装好的高级接口一把梭因为高级接口把底层细节都包起来了出了错反而不容易定位。最后再说一个心理层面的心得遇到 530/535 这种报错别慌也别急着到处搜答案。先把报错信息完整读一遍注意细节比如 Must issue a STARTTLS command first 已经把答案写在字面上了。再结合实际环境和配置逐步验证通常不需要多长时间就能定位到问题所在。而且毫不夸张地说这次踩坑经历让我后续在配置任何新的邮箱渠道比如企业邮箱、腾讯企业邮、其他供应商的 SMTP时基本都是一遍过。原理是相通的坑也就那么几个踩过一次就长记性了。
Spring Boot 发送 QQ 邮箱邮件从 530/535 错误到成功发送的全踩坑指南先说说我为什么写这篇。前阵子给一个项目加用户注册后的邮件验证码通知功能技术栈就是 Spring Boot邮箱选的 QQ 邮箱——因为项目方要求必须用 QQ 邮箱作为发件账号说是他们公司统一的企业邮箱流程还没走完先拿个人 QQ 邮箱顶上。我原本以为这事很简单Spring Boot 对邮件的支持非常成熟spring-boot-starter-mail一引application.yml里配几行JavaMailSender 直接用就完事了。结果从开始配到真正跑通整整折腾了一天半中间反复被 530 和 535 这两个错误码教做人。网上资料倒是不少但要么是零散的片段要么是直接把官方文档翻译一遍没有一个帖子能让我按着走完一遍不掉坑的。所以我把完整过程、错误码的底层含义、每一步的排查思路以及最终能直接照抄的配置方案全部整理出来。这篇文章不打算讲什么高深原理就当作一个踩坑记录和排查手册给后面接手同类需求的同学省点时间。1. 项目背景与核心需求拆解1.1 当时项目里为什么要发邮件那个阶段的项目是一个面向 C 端的 Web 服务用户注册需要绑定邮箱登录时支持邮箱验证码代替密码登录。在设计里邮箱验证码这一环承担了两个职能一是确认用户填写的邮箱确实是他本人的二是作为低安全级别操作的身份凭证。开发周期很紧没有单独搭消息中心服务的余裕所以邮件发送功能直接落在业务服务里走最朴素的方案——Spring Boot 内嵌的邮件发送能力。后期如果邮件发送量大了再拆出去也不迟接口层面先做好隔离就行。这种场景在中小型项目里非常典型。不需要上什么企业级的邮件推送平台也不需要搞复杂的消息队列异步化只要在业务代码里提供一个发邮件的 Service谁需要发邮件谁调一下就完事了。1.2 为什么发件账号选了 QQ 邮箱这个其实没有什么技术层面的考量和纠结纯粹是业务要求。但事后复盘QQ 邮箱作为发件方有一个不得不注意的技术特点它对第三方客户端的 SMTP 登录做了非常严格的安全限制必须使用授权码而不是登录密码必须走 SSL 加密连接。这两条限制恰好是后面所有坑的根源。因为 QQ 邮箱的这些限制导致网上 90% 的邮件发送相关教程只要是拿 QQ 邮箱做演示的几乎都有踩坑记录。反过来想只要把 QQ 邮箱这条路趟平了后面换任何一家邮箱服务商的 SMTP 都是降维操作原理完全一样无非改几个配置项。1.3 技术栈和版本说明我用的版本组合如下不同版本之间差异不大但为了后面照着配置不出偏差还是先列一下Spring Boot 2.7.xspring-boot-starter-mailJDK 1.8Maven 构建为什么特意提 JDK 版本因为 Spring Boot 2.7 在 JDK 8 下的行为跟在 JDK 11、17 下有些细微差别尤其是 SSL 相关的一些默认行为。我用 JDK 8 跑通了之后又在 JDK 11 环境里试了一遍发现只要配置方式一致结论是一样的。所以版本影响不大关键是配置项别搞错。2. 准备工作把 SMTP 服务先开通2.1 QQ 邮箱的 SMTP 服务必须在网页端开启很多人第一次搞这个上来就去改代码配置写完之后跑一下报错然后开始怀疑人生。实际上有个前置步骤漏了QQ 邮箱的 SMTP 服务默认是关闭的你不去网页端手动打开后面写什么都白搭。操作路径是登录 QQ 邮箱网页版 → 设置 → 账户 → 往下翻找到POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务这一栏 → 把 SMTP 服务的开关打开。打开的过程中会要求用手机发一条短信验证这是腾讯安全策略的一部分挺正常照着走就行。关键点来了开启 SMTP 服务之后会给你一串授权码记住这个授权码因为这就是你后面在代码里用来当密码的东西。QQ 邮箱的密码在这里是无效的只认授权码。我当时没仔细看提示拿着登录密码配了一把被 535 错误虐了半小时才反应过来。提示授权码只在第一次生成时完整显示后面再进到这个页面只会看到一串星号。如果你把授权码弄丢了只能删除后重新生成一个旧授权码立即失效。所以生成之后第一时间存好。2.2 搞清楚 SMTP 服务器地址和端口QQ 邮箱的 SMTP 配置信息是这样服务器地址是smtp.qq.comSSL 端口是465非 SSL 端口是25。这里建议直接用 465 加 SSL 的方式别去折腾 25 端口。25 端口在很多云服务商的网络环境里是被默认封禁的因为你买的服务器可能本身就部署了大量邮件服务运营商出于反垃圾邮件的考虑普遍把 25 端口直接禁掉。你可能在网上看到有人说用smtp.qq.com:587配合 STARTTLS 也能行这个对 QQ 邮箱来说不是最优解QQ 邮箱的 587 端口虽然开放但对 JavaMail 的兼容性不如 465 那么稳。我在实际测试中用 587 端口能通但第一次握手时如果 SSL 参数没配对很容易触发 530 错误。综合来看465 SSL 是最省心的组合。2.3 验证网络连通性在写任何代码之前先在命令行里验证一下你的服务器能不能连上smtp.qq.com的 465 端口。这一步能帮你把网络不通和代码错误这两个问题隔离开来。telnet smtp.qq.com 465如果 telnet 提示连接失败大概率是网络层面的问题先查防火墙、安全组策略或者干脆换一台网络环境干净的服务器再试。如果连接成功会进入一个黑窗口随便敲几个字母再关掉就行这个阶段不需要发什么命令能连上就说明网络畅通。这一步别跳过。我见过一些同事代码配了半天发现发不出去最后排查来排查去是测试环境服务器的 465 端口压根没放通。这个坑在本地开发时很少出现但在云服务器上太常见了。3. 第一个坑实录530 错误到底在说什么3.1 530 报错的现象我最初的配置是这样的spring: mail: host: smtp.qq.com port: 465 username: xxxqq.com password: xxxxxxxx代码就是一个很普通的发送逻辑Service public class MailService { Autowired private JavaMailSender mailSender; public void sendSimpleMail(String to, String subject, String content) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(xxxqq.com); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); } }跑起来之后异常日志里出现了这样一段com.sun.mail.util.MailConnectException: Couldnt connect to host, port: smtp.qq.com, 465; Caused by: javax.net.ssl.SSLException: Connection reset或者在某些情况下是Exception in thread main com.sun.mail.util.MailConnectException: Couldnt connect to host, hostsmtp.qq.com, port465当时一看到 SSLException 和 Connection reset我的第一反应是网络问题怀疑是不是 465 端口被封了。可是前面明明刚用 telnet 验证过端口是通的。那就很奇怪了端口通但握手失败问题肯定出在 SSL 层。3.2 网上搜到的答案和实际的原因遇到这个问题后我搜了一圈网上讨论最多的一个说法是缺了这样一段配置spring: mail: properties: mail: smtp: ssl: enable: true当时我确实没写这段。为什么没写因为我以为port: 465本身就暗示了走 SSL——毕竟 465 的全名就是SMTP over SSL的端口。但 JavaMailSender 的默认行为并不会因为你写了 465 就自动启用 SSL它需要显式声明mail.smtp.ssl.enabletrue才真的走 SSL 通道。这里需要展开讲讲原理。邮政模块底层用的是 JavaMail即 Jakarta MailJavaMail 在建立连接时默认认为你使用的是纯文本的 SMTP 协议。端口号是 465 也好是 25 也好对 JavaMail 来说只是连哪个端口的问题不代表它要自动升级到 SSL。所以你必须告诉它这个端口上的连接要用 SSL 加密。加了这段配置之后连接阶段算是过去了。但你以为这就完了并没有第二个坑马上接踵而至。3.3 SSL 配置正确后的 530 变体还有一种 530 错误长这样Caused by: javax.mail.AuthenticationFailedException: 530 5.7.1 Must issue a STARTTLS command first. y8sm8061678pfg.271 - gsmtp这个现象我后面模拟过发生在你用的是 STARTTLS 方式587端口但没有正确发送 STARTTLS 指令时。QQ 邮箱那边收到明文指令就不干了直接告诉你必须先走 STARTTLS。如果你走的是 465 SSL 路径理论上不会出现这个具体报错。但如果你的请求先尝试了 STARTTLS 失败又回退到非加密模式JavaMail 有时候会在日志里打印出类似 530 的内容很容易让人绕晕。所以这里有个经验原则选定一条加密路径就走到底不要混合着用。注意530 错误的本质是加密协商未完成而不是账号密码错误。遇到这种报错优先检查 SSL 是否显式启用其次检查端口是否匹配加密方式最后再看账号密码。4. 第二个坑实录535 错误的来龙去脉4.1 535 报错的完整日志SSL 配置对之后再次运行程序日志里弹出了新的错误码javax.mail.AuthenticationFailedException: 535 5.7.8 Username and password not accepted. y8sm8061678pfg.271 - gsmtp看到 Username and password not accepted 这个措辞你很容易联想到账号密码错了。我当时第一反应也是是不是用户名写错了是不是密码复制漏了字符然后我把用户名和密码反反复复检查了好几遍甚至换个平台重新复制了一次密码还是报同样的错误。后来才意识到这个密码根本不是邮箱登录密码而是授权码。我把邮箱的登录密码填进去了服务端当然拒绝。4.2 密码和授权码的区别是什么QQ 邮箱的授权码相当于一个为第三方客户端单独生成的专用密码它的权限范围其实也挺大——能操作你的邮件收发。但是好处是它跟登录主密码是独立的你可以在任何设备上单独吊销授权码而不用改主密码防止其他客户端被连带踢下线。所有支持 SMTP 的国内主流邮箱服务商都有类似的机制。QQ 邮箱生成授权码的过程在 2.1 里写过了不再重复。核心记住一句话代码里的 password 字段填的是授权码不是 QQ 密码。提示如果在网页端重新生成了授权码旧的授权码立即失效。如果代码里配置的授权码是旧的下次发送就会立刻被打回 535 错误。排查的时候如果之前好好的、突然开始报 535优先回想一下是不是最近重置过授权码。4.3 535 错误的另一种可能账号书写格式还有一个容易被忽视的细节用户名要写完整的邮箱地址比如someoneqq.com不能只写someone。有些邮箱服务商支持只写账号前缀但 QQ 邮箱严格要求全地址格式。这个在报错信息里不容易看出来因为服务端只会告诉你 auth 失败不告诉你具体是格式问题还是值的问题。所以排查 535 时检查清单里加上一条用户名是不是完整邮箱格式。把这几个点都走通之后程序终于不再报错了我一封测试邮件顺利发送成功。但整个项目里邮件发送功能不能只跑通一个最简单的场景后面还有更多细节要处理。5. 完整可复用的邮件发送封装5.1 配置文件的最终形态下面直接给出我验证过可以稳定运行的完整配置复制过去改掉账号和授权码就能用spring: mail: host: smtp.qq.com port: 465 username: yournameqq.com password: 你的授权码 default-encoding: UTF-8 properties: mail: smtp: socketFactory: class: javax.net.ssl.SSLSocketFactory ssl: enable: true auth: true starttls: enable: false这里有三个配置项值得单独说明一下smtp.authtrue表示 SMTP 连接需要进行身份认证。不写的话JavaMail 默认确实是不开启认证的那服务端连接过来之后不送账号密码直接被拒。Spring Boot 的spring.mail.username/password配置虽然提供了值但底层 JavaMail 是否启用了 AUTH 指令需要看这个auth参数。实际测试中发现有些版本不写也自动带上但显式声明更稳妥。socketFactory.class指定使用javax.net.ssl.SSLSocketFactory来创建套接字。这相当于显式告诉 JavaMail所有通信都要经过 SSL 套接字。这个配置和mail.smtp.ssl.enabletrue的作用有重叠本质上都指向启用 SSL区别在于前者更偏底层兼容性更好。starttls.enablefalse明确关闭 STARTTLS。因为走的是 465 端口直连 SSL不需要 STARTTLS 这一层关了反而干净避免 JavaMail 在某些情况下优先尝试 STARTTLS 引发 530 变体。5.2 JavaMailSender 封装代码最终我在项目里保留了一个偏向业务的 Service。底层 Spring 已经帮我们把JavaMailSender接口实现好了直接用就行。为了提高复用性我封装了三个方法纯文本、富文本 HTML、带附件。下面贴出核心代码。首先是纯文本邮件适合验证码、通知类简单场景Service public class MailService { Value(${spring.mail.username}) private String from; Autowired private JavaMailSender mailSender; public void sendSimpleMail(String to, String subject, String content) { SimpleMailMessage message new SimpleMailMessage(); message.setFrom(from); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); } }这里from直接取配置文件里的 username避免在代码里硬编码邮箱地址。有一个细节setFrom如果跟配置的 username 不一致部分邮箱服务商可能会拒绝发送。QQ 邮箱对发件人地址的校验比较严格最好保持一致。5.3 富文本 HTML 邮件验证码邮件虽然简单但业务里往往还涉及营销通知、欢迎邮件这类更需要样式的场景。这种邮件建议直接用 HTML 格式发送SimpleMailMessage就不够用了改用MimeMessagepublic void sendHtmlMail(String to, String subject, String htmlContent) throws MessagingException { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(from); helper.setTo(to); helper.setSubject(subject); helper.setText(htmlContent, true); mailSender.send(message); }MimeMessageHelper的第二个参数true表示启用 multipart 模式这样邮件正文可以携带内嵌资源和附件。第三个参数指定字符集为 UTF-8这一步非常重要不然 HTML 内容里的中文在客户端显示时会变成乱码。helper.setText(htmlContent, true)里的第二个参数true就是告诉 JavaMail 这段文本是 HTML 而不是纯文本。很多人漏了这个参数结果发出去的邮件显示的是源代码一长串div标签直接码在内容区特别尴尬。5.4 带附件的邮件业务里涉及导出报表、合同文件之类的场景就需要附件能力。代码如下public void sendAttachmentMail(String to, String subject, String text, File attachment) throws MessagingException, IOException { MimeMessage message mailSender.createMimeMessage(); MimeMessageHelper helper new MimeMessageHelper(message, true, UTF-8); helper.setFrom(from); helper.setTo(to); helper.setSubject(subject); helper.setText(text, false); helper.addAttachment(attachment.getName(), attachment); mailSender.send(message); }addAttachment支持传入File、InputStreamSource等类型。如果你是从内存里生成的文件比如 Excel 导出流用ByteArrayResource或者InputStreamResource包一下再传进去这样避免先把临时文件写到磁盘上的额外开销。5.5 解决 mailsender 自动装配的问题某个同事在照着我这个方案配置时遇到一个怪问题Autowired private JavaMailSender mailSender;这一行报错提示没有JavaMailSender类型的 Bean。明明依赖加了吗加了。配置配了吗配了。后来发现他的类被放在了启动类能扫描到的包外面Spring 没有扫描到所以那些自动配置类生成的 Bean 也注入不进去。这不是邮件模块特有的问题是 Spring Boot 包扫描的基本边界问题。把类移到启动类同级或子包内就解决了。另一个场景是项目里有多套邮件配置可能会注入多个JavaMailSender实例。这种场景下用Qualifier或者按配置中心设定来区分 Bean就属于进阶玩法了这里不展开。6. 常见问题与排查技巧实录6.1 错误速查表下面这张表是根据我实际踩过的、以及帮同事排查过的各种问题整理而来。以后遇到同类报错先对照这个表定位方向报错现象常见原因排查步骤MailConnectException: Connection resetSSL 未显式启用检查 ssl.enable 和 socketFactory.class 配置530 5.7.1 Must issue a STARTTLS command firstSSL/STARTTLS 方式混用确认端口和加密方式一致性465 就走纯 SSL535 5.7.8 Username and password not accepted授权码错误或使用了登录密码重新生成授权码确认 password 字段用的是授权码535 5.7.0 Must issue a STARTTLS command first465 端口配了 starttls.enabletrue将 starttls.enable 设为 false454 4.7.0 Temporary authentication failure服务器时间偏差或 IP 信誉问题校准服务器时间更换发件 IP 测试连接 25 端口超时云服务商封禁 25 端口换 465 端口走 SSL6.2 发件人显示名称的问题纯文本邮件默认发件人显示的是邮箱地址邮件的发件人一栏会显示xxxqq.com很不美观。想显示成某某系统这样的名称在 MimeMessageHelper 里用这样写helper.setFrom(from, 某某系统);原理是利用了 MIME 协议里发件人字段的编码格式把显示名称和地址拼在了一起。国内大厂的邮箱客户端对中文发件人名称的支持都很好可以放心用。6.3 异步发送的必要性在业务里直接同步发送邮件有一个隐患如果 SMTP 服务端响应慢当前线程就会被阻塞用户那边表现为接口迟迟不返回。更糟糕的情况是SMTP 服务端临时不可用mailSender.send()抛出异常直接导致整个业务操作失败——用户本来只是注册个账号结果因为邮件服务不可用注册请求也跟着失败。所以生产环境里一定把邮件发送放到异步线程池里去。Spring 自带Async注解配一个线程池就能用。不过要注意异常处理异步方法里的异常不会抛给调用方要在方法内部捕获处理记录日志否则邮件发送失败时会静默丢失。6.4 我在重试策略上的配置心得生产环境的邮件发送我习惯加上重试机制。这个重试不是说代码里自己写个 for 循环而是让消息先落到本地表或者消息队列里。一个简单的设计是建一张邮件发送记录表状态字段记录待发送、已发送、发送失败。定时任务扫描发送失败且重试次数未到上限的记录再次触发发送。这样做的收益非常直接即便 SMTP 服务商临时故障消息不会丢等故障恢复后定时任务会自动把积压的邮件发出去。我在那个项目里就用了这个方案上线之后邮件发送的成功率几乎到了 99.9%剩下的那 0.1% 是用户的邮箱地址本身写错了。6.5 邮件正文中的图片处理邮件正文如果要带图片有两种方式一种是图片放到图床/CDN正文里用img srchttps://...引用另一种是把图片作为内嵌资源放进邮件里。前者实现简单但有些邮箱客户端在加载远程图片时会要求用户手动点一下显示图片体验打折。后者更稳妥相当于把图片塞进了邮件本体打开就能看到。内嵌实现方式是在MimeMessageHelper中调用addInlinehelper.addInline(logo, new ClassPathResource(logo.png));然后在 HTML 里通过cid:logo来引用img srccid:logo用了addInline之后邮件整体体积会变大但这类内嵌资源通常是几十 KB 级别的 logo 或小图在可接受范围内。如果非要附带几 MB 的高清图那建议还是放图床不然用户体验会很差。6.6 关于测试环境的实测结论在本地开发环境里我第一次成功发送邮件后又在测试环境跑了一轮。测试环境的服务器是某云厂商的轻量级服务器安全组策略默认只放行 80/443/22 等常见端口465 端口初始是封着的。同样一段代码本地 OK上了测试环境就超时。这个差异让我当时一度以为是代码移库时装坏了什么东西实际上是云厂商安全组的惯性判断。所以如果你是在云服务器上部署项目除了代码之外一定记得打开安全组规则里对应 SMTP 端口的出站方向访问权限。虽然大多数云平台对出站方向限制较少但少数平台在轻量应用服务器上做了额外限制这个东西在控制台里就能设置不需要提交工单。6.7 授权码泄露的应对授权码本质上就是密码级别的机密信息如果写在了代码仓库里那就等于把邮件账号拱手让人。为了避免这个问题配置里不要硬编码授权码改成环境变量注入spring: mail: password: ${MAIL_AUTH_CODE}然后在服务器或者 CI/CD 工具中配置MAIL_AUTH_CODE这个环境变量。这样即使代码不小心被推到公开仓库授权码也不会暴露。如果不幸授权码还是泄露了第一时间登录 QQ 邮箱网页端在设置里删除旧的授权码并重新生成把泄露的凭证作废掉不要抱着应该没事吧的侥幸心理。重置之后代码里的配置也要同步更新到位不然下次发送又是一记 535。7. 从这次踩坑里总结出的通用经验走完这一趟我对邮件发送这件事的复杂度有了新的认识表面上看它就是往配置里填几行参数的事实际上每一步都藏着影响成败的暗桩。先说说我对这些报错码的新理解。530 并不是世界末日它本质上是在提醒你SSL/STARTTLS 这层加密没谈拢。排查它的时候脑子里要先有一个清晰的链路图Socket 建立 → 加密协商 → 身份认证 → 邮件指令 → 退出登录。530 发生在加密协商阶段535 发生在身份认证阶段阶段不同排查方向完全不同。其次是配置中心化的重要性。一个小项目可以接受把配置直接写在 yml 里但只要项目规模上来多环境、多项目复用邮件配置散落在各处就是噩梦。我现在更倾向于把邮件配置单独用一个配置类管理代码里只面向接口编程具体用哪家邮箱服务商、哪个发件账号由环境决定。还有一点是日志的重要性和敏感性。JavaMail 可以开启调试模式打印出跟 SMTP 服务器交互的完整明文对话。这个模式在排查问题时非常好用能直观看到客户端和服务端每一步的往来。但也正因为它是明文的调试日志里会带着授权码信息线上环境绝不可能随意开着。我当时在本地开了调试模式定位完问题就立刻关掉了。调试模式的开启方式spring: mail: properties: mail: debug: true输出的日志会包含DEBUG SMTP: connected to host...、DEBUG SMTP: AUTH command failed这类信息对定位问题很有帮助。这次的经历也让我养成了一个习惯但凡用邮件服务先写一段基于 JavaMail 的探针代码把连接、认证、发信这几个环节拆开单独验证哪个环节挂了一目了然。不要直接用 Spring Boot 包装好的高级接口一把梭因为高级接口把底层细节都包起来了出了错反而不容易定位。最后再说一个心理层面的心得遇到 530/535 这种报错别慌也别急着到处搜答案。先把报错信息完整读一遍注意细节比如 Must issue a STARTTLS command first 已经把答案写在字面上了。再结合实际环境和配置逐步验证通常不需要多长时间就能定位到问题所在。而且毫不夸张地说这次踩坑经历让我后续在配置任何新的邮箱渠道比如企业邮箱、腾讯企业邮、其他供应商的 SMTP时基本都是一遍过。原理是相通的坑也就那么几个踩过一次就长记性了。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
