Spring Boot发送QQ邮箱邮件：530/535错误排查与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.x
• spring-boot-starter-mail
• JDK 1.8
• Maven 构建

为什么特意提 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.com，SSL 端口是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: [e-mail] 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("[e-mail]"); message.setTo(to); message.setSubject(subject); message.setText(content); mailSender.send(message); } }

跑起来之后，异常日志里出现了这样一段：

com.sun.mail.util.MailConnectException: Couldn't 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: Couldn't connect to host, host=smtp.qq.com, port=465

当时一看到 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.enable=true才真的走 SSL 通道。

这里需要展开讲讲原理。邮政模块底层用的是 JavaMail（即 Jakarta Mail），JavaMail 在建立连接时，默认认为你使用的是纯文本的 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 错误的另一种可能：账号书写格式

还有一个容易被忽视的细节：用户名要写完整的邮箱地址，比如[e-mail]，不能只写someone。有些邮箱服务商支持只写账号前缀，但 QQ 邮箱严格要求全地址格式。这个在报错信息里不容易看出来，因为服务端只会告诉你 auth 失败，不告诉你具体是格式问题还是值的问题。所以排查 535 时，检查清单里加上一条：用户名是不是完整邮箱格式。

把这几个点都走通之后，程序终于不再报错了，我一封测试邮件顺利发送成功。但整个项目里邮件发送功能不能只跑通一个最简单的场景，后面还有更多细节要处理。

5. 完整可复用的邮件发送封装

5.1 配置文件的最终形态

下面直接给出我验证过可以稳定运行的完整配置，复制过去改掉账号和授权码就能用：

spring: mail: host: smtp.qq.com port: 465 username: [e-mail] password: 你的授权码 default-encoding: UTF-8 properties: mail: smtp: socketFactory: class: javax.net.ssl.SSLSocketFactory ssl: enable: true auth: true starttls: enable: false

这里有三个配置项值得单独说明一下：

smtp.auth=true表示 SMTP 连接需要进行身份认证。不写的话，JavaMail 默认确实是不开启认证的，那服务端连接过来之后不送账号密码，直接被拒。Spring Boot 的spring.mail.username/password配置虽然提供了值，但底层 JavaMail 是否启用了 AUTH 指令，需要看这个auth参数。实际测试中发现，有些版本不写也自动带上，但显式声明更稳妥。

socketFactory.class指定使用javax.net.ssl.SSLSocketFactory来创建套接字。这相当于显式告诉 JavaMail：所有通信都要经过 SSL 套接字。这个配置和mail.smtp.ssl.enable=true的作用有重叠，本质上都指向"启用 SSL"，区别在于前者更偏底层，兼容性更好。

starttls.enable=false明确关闭 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就不够用了，改用MimeMessage：

public 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 reset	SSL 未显式启用	检查 ssl.enable 和 socketFactory.class 配置
530 5.7.1 Must issue a STARTTLS command first	SSL/STARTTLS 方式混用	确认端口和加密方式一致性，465 就走纯 SSL
535 5.7.8 Username and password not accepted	授权码错误或使用了登录密码	重新生成授权码，确认 password 字段用的是授权码
535 5.7.0 Must issue a STARTTLS command first	465 端口配了 starttls.enable=true	将 starttls.enable 设为 false
454 4.7.0 Temporary authentication failure	服务器时间偏差或 IP 信誉问题	校准服务器时间；更换发件 IP 测试
连接 25 端口超时	云服务商封禁 25 端口	换 465 端口走 SSL

6.2 发件人显示名称的问题

纯文本邮件默认发件人显示的是邮箱地址，邮件的发件人一栏会显示[e-mail]，很不美观。想显示成"某某系统"这样的名称，在 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 src="https://...">引用；另一种是把图片作为内嵌资源放进邮件里。前者实现简单，但有些邮箱客户端在加载远程图片时会要求用户手动点一下"显示图片"，体验打折。后者更稳妥，相当于把图片塞进了邮件本体，打开就能看到。

内嵌实现方式是在MimeMessageHelper中调用addInline：

helper.addInline("logo", new ClassPathResource("logo.png"));

然后在 HTML 里通过cid:logo来引用：

<img src="cid: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）时，基本都是一遍过。原理是相通的，坑也就那么几个，踩过一次就长记性了。