邮件发送这个功能很多项目在开发阶段就跑通了上线之后却突然开始抛Mail server connection failed; Could not connect to SMTP host。这个报错最让人头疼的地方在于——它把好几类完全不同的问题压缩成了一句话端口写错、加密方式错配、出网被拦、DNS 解析到不可达地址、容器缺根证书、甚至用户名写成授权码最后都有可能长成这副模样。我前后在四五个项目里处理过这个异常最坑的一次是本地跑得好好的一上服务器就报连不上查了两个小时才发现是端口和加密开关没对上客户端一直在等服务端先说话服务端一直在等客户端先握手双方僵到超时。下面我按“先读懂异常、再切分链路、最后落到配置和兜底”的顺序把这条报错从表象到根因拆一遍。适合正在被这个问题卡住的后端同学也适合刚接手邮件模块、想一次性把配置写对的人。文中涉及的主机名、账号一律用占位示例配置片段可以直接替换后使用。1. 先把异常堆栈读透MailConnectException 咬的是哪一段1.1 三层异常嵌套每一层都在告诉你不同的事JavaMailSender抛出的完整堆栈通常长这样注意从外到内读org.springframework.mail.MailSendException: Mail server connection failed; nested exception is com.sun.mail.util.MailConnectException: Could not connect to SMTP host: smtp.example.com, port: 465, response: -1最外层MailSendException是 Spring 的统一封装它本身不含信息量只说明“发送动作失败了”。真正有价值的是中间那层MailConnectException这是 JavaMail 实现里的连接异常它明确告诉你连接在TCP 建立或协议握手阶段就断了消息根本没有被投递出去。最后的response: -1是关键判据——-1表示客户端没有从服务端读到任何 SMTP 响应码。这里有个非常实用的判断技巧看 response 后面跟的是 -1 还是三位数字。如果是response: 535、550、553这类具体码说明 TCP 已经通了服务端也回了话问题在认证或发件人校验跟“连不上”是两回事如果永远是-1那才真的是链路层没打通或者握手失败。很多人被这条报错带偏一看到 “Could not connect” 就去改密码其实密码根本还没被送出去。另外要留意有没有MailAuthenticationException。Spring 把它和连接异常分开了认证失败会单独抛这个类型。但现实里有些邮件服务端在 TLS 握手失败或者 IP 被限制时会直接掐断连接客户端拿到的仍然是MailConnectException所以不能只靠异常类型下结论还是要结合 response 码和日志时间点判断。1.2 连接阶段、握手阶段、认证阶段三种失败长得像但根因完全不同我习惯把一次 SMTP 交互拆成三个时间窗口出问题先定位落在哪个窗口阶段典型耗时特征可能的异常优先怀疑TCP 三次握手一直卡到超时默认可能是无限MailConnectExceptionresponse: -1DNS、端口未放行、安全组、目标地址不可达TLS 握手卡住或几秒内断开MailConnectException / SSLHandshakeException 包装后端口与加密方式错配、证书链、容器缺 CA、系统时间认证与投递快速返回MailAuthenticationException 或 535/550用户名格式、授权码、发件人域名校验判断落在哪个窗口看两件事就够了日志里从发起请求到抛异常花了多久以及有没有出现SSLHandshakeException、PKIX path building failed这类被包在里面的 cause。卡满超时时间才抛大概率是 TCP 层没通一两秒就断往往是握手或服务端主动拒绝。这个判断能省掉一大半无效排查。我踩过的一个典型误判某次线上报错日志显示连接失败我第一反应是网络策略调整了结果翻完整堆栈发现最里层藏着java.security.cert.CertPathValidatorException。证书校验失败被 JavaMail 包成了连接异常光看外层那句话完全看不出来。所以永远要把Caused by链拉到底别只看第一行。2. 端口和加密方式错配这条报错最高频的来源2.1 25、465、587 三个端口握手方式根本不是一回事邮件提交端口的差异是这条报错最常见也最容易忽略的根因。三者的行为完全不同25 端口传统明文 SMTP先明文打招呼需要加密再通过 STARTTLS 命令升级。很多云主机默认限制出网 25 端口用来抑制垃圾邮件外发所以本地通、服务器不通是常态。465 端口隐式 SSL早年叫 SMTPSTCP 连上之后立刻开始 TLS 握手没有明文阶段。587 端口明文连接 STARTTLS 显式升级是现在主流的提交端口认证通常在升级之后进行。错配是怎么发生的举个最典型的配置写了 465但mail.smtp.ssl.enable没开。客户端连上 TCP 后按明文发EHLO而服务端在等 TLS ClientHello两边互相等最后客户端超时抛出来的就是Could not connect ... response: -1。反过来587 端口上把ssl.enable设成 true客户端直接发 ClientHello 打到明文端口服务端通常直接断开连接表现也是一两秒内失败。所以看到这条报错第一件事不是改密码是核对端口号与两个开关ssl.enable、starttls.enable是否成对。这三者必须作为一个整体来配拆开看没有意义。2.2 ssl.enable 和 starttls.enable 不是二选一语义完全不同很多人以为这两个开关是对立的其实它们控制的是两个不同的动作mail.smtp.ssl.enabletrue连接建立后立即启用 TLS适用于 465。mail.smtp.starttls.enabletrue先明文连接再发STARTTLS命令升级适用于 587 和 25。mail.smtp.starttls.requiredtrue升级失败就报错中止而不是降级为明文继续。第三个参数值得单独说。默认情况下starttls.enabletrue只是尝试升级如果服务端不支持某些实现会悄悄退回明文继续。这在生产环境是隐患所以走 587 时我一般把required也设为 true宁可失败也不要明文传输凭据。还有一个冷门但真实的坑个别服务端的 587 端口在 STARTTLS 之后才允许AUTH如果你把mail.smtp.auth关了会在握手成功后立刻收到530 Authentication required而某些客户端版本会把这个阶段的问题也包装成连接异常。所以auth参数也要一起确认。2.3 两套可以直接抄的配置模板465 隐式 SSL 的写法spring: mail: host: smtp.example.com port: 465 username: no-replyexample.com password: ${MAIL_AUTH_CODE} default-encoding: UTF-8 properties: mail: smtp: auth: true ssl: enable: true connectiontimeout: 5000 timeout: 5000 writetimeout: 5000587 STARTTLS 的写法spring: mail: host: smtp.example.com port: 587 username: no-replyexample.com password: ${MAIL_AUTH_CODE} default-encoding: UTF-8 properties: mail: smtp: auth: true starttls: enable: true required: true connectiontimeout: 5000 timeout: 5000 writetimeout: 5000注意username一般要写完整邮箱地址不是 前面那一截。有些服务端接受短名有些直接拒绝为了可移植性统一写全。密码位置放的是申请来的授权码/应用专用密码不是账号登录密码——这一点后面还会展开。敏感信息别硬编码进 yml。我一般的做法是通过环境变量注入本地开发用.env或者 IDE 的运行配置容器里用编排工具的密钥管理能力源码仓库里只留${MAIL_AUTH_CODE}这种占位符。这不是洁癖是防止某天仓库权限外泄时连带把发信能力一起送出去。3. 从应用主机出发把链路一段段掐断来验3.1 先确认解析结果再看它是不是你想要的那个地址报错里的 host 是应用自己解析出来的。如果 DNS 返回了多条记录客户端通常按顺序尝试第一条不通就超时根本轮不到第二条。先看解析getent hosts smtp.example.com # 或者 nslookup smtp.example.com 8.8.8.8重点看两件事有没有 AAAA 记录IPv6以及返回的地址是不是你能访问的那一组。容器环境里很常见的情况是——DNS 同时返回 IPv4 和 IPv6JVM 优先尝试 IPv6而宿主机的容器网络没有 IPv6 出口于是一路超时。表现就是有的机器能发、有的机器不能发非常迷惑。这种情况有两个处理方向一是给 JVM 加参数-Djava.net.preferIPv4Stacktrue强制走 IPv4二是干脆在容器网络层把 IPv6 关掉。我更倾向第一种改动小、可回滚。加参数后重启应用再发一封如果立刻通了基本可以确认是这个原因。还有一种低频情况解析到的是内网地址或者上一轮迁移遗留的旧地址。这时候连通性测试全通但那个地址上的 SMTP 服务根本不提供你需要的功能或者直接拒绝连接。所以测试前一定先打印解析结果别拿一个错误的目标去测。3.2 用命令行从目标机器上实测端口不要在本地测这一步是分水岭。很多人的排查方式是我本地用邮件客户端能发啊但应用跑在另一台机器上网络路径完全不同。必须登到应用所在的那台机器上去测。# 测 TCP 能不能通 timeout 5 bash -c cat /dev/null /dev/tcp/smtp.example.com/465 echo tcp ok || echo tcp fail # 或者用 nc nc -vz -w 5 smtp.example.com 465 # 测 TLS 握手和证书 openssl s_client -connect smtp.example.com:465 -servername smtp.example.com -briefopenssl s_client是排查这条报错最有价值的单条命令因为它一次给你三份信息TCP 是否可达、TLS 是否能协商成功、证书的签发者与有效期。如果它报connect: Connection timed out问题在网络层如果报verify error: unable to get local issuer certificate问题在信任链如果握手成功但证书notAfter已经过期那应用侧一定失败。顺手看一眼系统时间date -u时间偏差超过证书有效期容差通常几分钟到几十分钟校验就会失败。容器里时钟漂移不是稀罕事尤其是长期不重启的实例。这种情况报错文案和连不上几乎一样很容易被误判成网络问题。3.3 本地通、服务器不通出网策略与端口限制的典型形态这个场景我遇到过至少三次每次都是同一个套路开发环境在公司办公网25、465、587 全都放行生产环境在受限的云上网络出方向只开了 80 和 443邮件端口一律不通。区分方法很简单做对照实验测试项结果结论目标 465 端口 TCP 不通fail出网策略、安全组或目标侧限流目标 587 端口 TCP 通ok端口策略按端口粒度配置换端口可解目标 443 端口通比如访问任意 HTTPS 站点ok机器本身有正常出网能力排除整体断网同一目标从另一台机器测通ok问题定位在本机出网规则如果确认是出网策略限制处理方式无非两种申请放通对应端口或者换成服务商提供的、允许在已开放端口上提交的通道。这里不要抱侥幸心理去试各种旁路方案正规做法就是走网络策略变更流程同时在代码里做好失败兜底别让邮件发不出去把主业务流程拖垮。3.4 容器精简镜像缺根证书握手会失败得很像连不上用精简基础镜像构建的应用/etc/ssl/certs或者ca-certificates包经常是缺失的。表现是宿主机上openssl s_client一切正常容器里跑应用就报连接失败堆栈深处藏着PKIX path building failed或者unable to find valid certification path。验证方式是在容器里执行ls /etc/ssl/certs | head # 或者直接测 openssl s_client -connect smtp.example.com:465 -servername smtp.example.com如果容器里没有openssl命令那本身就是个信号——这个镜像太精简了。修复方式是在 Dockerfile 里补上证书包RUN apk add --no-cache ca-certificates update-ca-certificates # Debian 系 RUN apt-get update apt-get install -y --no-install-recommends ca-certificates企业内网如果有自建证书体系还需要把内部根证书导入 JVM 的信任库cacerts或者通过-Djavax.net.ssl.trustStore指定。这一步容易被跳过因为本地开发机通常装了一堆根证书什么问题都没有一进容器就炸。4. 配置看起来没问题却还是报错框架层的细节陷阱4.1 host 字段只填主机名别把协议和端口塞进去spring.mail.host期望的是纯主机名。我见过写成smtps://smtp.example.com的也见过写成smtp.example.com:465的。前者会导致 DNS 解析一个带协议头的字符串必然失败后者看起来合理但端口被拼进 host 之后实际连接的目标就变成了smtp.example.com:465:465这种畸形地址JavaMail 会直接抛连接异常。正确的做法是 host 和 port 分开写。这个坑的特征是报错里的 host 值明显带着冒号或斜杠。所以看日志时先核对报错里打印的 host 和 port 是不是你预期的值这一步能立刻排除掉一类低级但高频的错误。另外注意spring.mail.properties.mail.smtp.*这一层的路径。Spring Boot 会把spring.mail.properties下的所有键平铺成 JavaMail 的 Session 属性所以必须是mail.smtp.xxx开头少一层mail或者把smtp和ssl的顺序写错配置不会报错只是不生效——然后你就得到一条配置明明写了却没起作用的诡异现象。4.2 超时参数默认接近无限卡住时连日志都没有JavaMail 的三个超时属性默认值是无限等待这意味着网络不通时线程会一直挂着直到操作系统层面的 TCP 超时可能几分钟。表现出来就是发邮件的接口长时间无响应日志里没有任何异常最后要么被上游网关掐断要么线程池被拖满。三个参数的分工要搞清楚参数作用建议值mail.smtp.connectiontimeout建立 TCP 连接的等待时间3000~5000 msmail.smtp.timeout等待服务端响应的读超时5000~10000 msmail.smtp.writetimeout发送数据的写超时5000~10000 ms单位是毫秒值以字符串形式传入。三个都要设只设一个的话另外两个仍然是无限。我一般统一设 5 秒邮件这种非实时业务5 秒拿不到结果就当失败处理然后进补偿流程比让请求挂在那里好得多。设了超时之后还有个好处报错会变快你能立刻拿到异常并看到堆栈而不是等几分钟后从网关的 504 里反推。4.3 Spring Boot 版本升级带来的 javax / jakarta 分叉Spring Boot 3 开始邮件相关 API 从javax.mail迁移到了jakarta.mail。如果你升级了主框架版本但依赖没跟上或者反过来引了两个版本的 mail 实现会出现一类很迷惑的现象应用能启动注入正常但一调用发送就在连接阶段抛异常堆栈里往往伴随NoSuchMethodError或ClassNotFoundException。排查方式mvn dependency:tree -Dincludes*mail* # Gradle ./gradlew dependencies --configuration runtimeClasspath | grep -i mail确认jakarta.mail-api和具体实现如angus-mail版本一致且没有残留javax.mail的传递依赖。这一步在 Boot 2 升 3 的项目里几乎是必做的别指望编译器提醒你。4.4 认证失败有时也被伪装成连接失败前面说过要看 response 码这里补充几个常见混淆点密码位置填了登录密码而不是授权码。多数服务商在开启 SMTP 服务时会给一串独立的应用密码直接用账号密码认证会被拒。用户名没写全。no-reply和no-replyexample.com在不同服务端行为不一致。发件人地址与认证账号不一致。有些服务端要求From必须是认证账号或其别名否则投递阶段返回553。这个不属于连接问题但因为它发生在同一次调用的后半段日志混在一起容易看错。服务端对该来源 IP 做了限制。表现可能是握手后立刻断开客户端拿到的仍是连接异常。我一般的定位流程是先用openssl s_client确认握手能成再用一段最小化的 Java 代码单独跑认证把业务代码的干扰排除掉。最小化验证能跑通问题一定在配置或依赖跑不通问题在凭证或服务端策略。5. 几个真实项目里踩出来的坑5.1 连接池复用遇上中间设备静默断连JavaMail 默认每次发送新建连接但如果为了性能开了mail.smtp.connectionpooltrue就要面对连接被中间网络设备回收的问题。表现是服务刚启动时发送正常跑几个小时后开始零星报连接失败重启后又好一阵。这类问题的特征是失败率随运行时长上升且集中在低峰期后的第一次发送。原因是池里的连接在空闲时被链路上的设备清掉了但客户端不知道仍然拿旧连接去写数据写到一半才发现对端已经关闭。处理方式有两种一是关闭连接池接受每次建连的开销对低频发送完全够用二是保留连接池但把mail.smtp.timeout设小并在捕获到连接类异常时做一次销毁当前 sender、重建连接的重试。我倾向第一种邮件量不大的系统没必要为这点性能引入状态管理。5.2 异步发送把异常吞得干干净净用Async包装发送逻辑很常见目的是不阻塞主流程。问题在于异步方法里抛出的异常默认不会传播到调用方如果没配AsyncUncaughtExceptionHandler异常只会打一条日志甚至因为日志级别不够而彻底消失。结果就是业务侧显示发送成功因为方法是 void实际上邮件从来没出去。等用户投诉没收到验证码回头查日志才发现早就在报Could not connect。我的做法是异步方法返回CompletableFutureVoid或者干脆把发送结果落一张表状态流转为待发送 → 已提交 → 已成功/已失败失败带错误摘要。这样邮件问题变成可观测的业务数据而不是埋在日志里的异常。同时给AsyncConfigurer配上异常处理器保证任何漏网的异常都能进告警。5.3 把发信能力放在主链路上一次网络抖动就是一次故障这个不是技术坑是设计坑。早期有个项目用户注册接口里同步调发送邮件邮件服务一抖动注册接口跟着 500。后来改成注册只负责落库并投递一条消息独立的发送任务消费消息、带重试、失败进死信表人工兜底。改造之后有几个明显收益注册接口的 P99 不再受邮件服务影响发送失败可以按退避策略重试比如 1 分钟、5 分钟、30 分钟各一次重试次数用尽后进人工队列运营可以手动补发。这套结构对任何外部依赖都适用不只是邮件。6. 一套可复用的定位顺序与线上兜底设计6.1 五步定位法从最外层异常一路收敛到根因被这条报错卡住时我按下面这个顺序走基本能在十几分钟内收敛拉全堆栈确认 response 是 -1 还是三位码确认有没有SSLHandshakeException、PKIX之类的内层 cause。核对端口与加密开关的配对465 配ssl.enable587 配starttls.enable requiredhost 里不能带协议和端口。在应用所在机器上测连通性nc -vz测 TCPopenssl s_client测握手与证书date -u看系统时间。检查出网策略用不同端口做对照实验确认是端口级限制还是整体不通顺带确认 DNS 是否解析到了 IPv6 而容器没有 IPv6 出口。最后才怀疑凭证用最小化代码单独验证认证排除业务代码和依赖版本的干扰。这个顺序的价值在于从便宜的操作往贵的操作排前四步都是命令行几分钟能完成的最后一步要写代码、要申请凭证放最后。6.2 生产环境该有的兜底可重试与不可重试要分开不是所有失败都值得重试。判断标准很简单异常类型是否重试理由连接超时、握手超时是退避重试 2~3 次大概率是瞬时网络抖动认证失败535否凭证错了重试多少次都一样还会触发风控收件人不存在550否数据问题重试无意义服务端限流421/450是拉长间隔需要给对端缓冲时间实现上把异常按类型分流只对白名单内的异常走重试队列其余直接落失败表并告警。同时给整个发送环节加一个总开关出问题时能一键降级为只落库不发送避免故障期间把线程资源全耗在等待超时上。还有一个容易被忽略的点告警要带上下文。只报邮件发送失败没有意义要带 host、port、response 码、异常首行、失败次数的环比变化。有了这些值班的人不用登机器就能判断是配置问题还是网络问题。最后分享一个我自己一直在用的小习惯把上面那套openssl s_client、nc -vz、date -u写成一段脚本随应用镜像一起打包进去。下次再看到Could not connect to SMTP host在容器里跑一下脚本三十秒内就能知道是链路、证书还是时间的问题比翻文档快得多。这个脚本我前后改过几版现在连目标端口和是否走 STARTTLS 都能自动判断算是被这条报错逼出来的一点副产品。 
长河君 · 2026/11/5 6:06:06 · 阅读 1.2k SMTP 邮件连接失败排障：端口加密、证书与超时定位
邮件发送这个功能很多项目在开发阶段就跑通了上线之后却突然开始抛Mail server connection failed; Could not connect to SMTP host。这个报错最让人头疼的地方在于——它把好几类完全不同的问题压缩成了一句话端口写错、加密方式错配、出网被拦、DNS 解析到不可达地址、容器缺根证书、甚至用户名写成授权码最后都有可能长成这副模样。我前后在四五个项目里处理过这个异常最坑的一次是本地跑得好好的一上服务器就报连不上查了两个小时才发现是端口和加密开关没对上客户端一直在等服务端先说话服务端一直在等客户端先握手双方僵到超时。下面我按“先读懂异常、再切分链路、最后落到配置和兜底”的顺序把这条报错从表象到根因拆一遍。适合正在被这个问题卡住的后端同学也适合刚接手邮件模块、想一次性把配置写对的人。文中涉及的主机名、账号一律用占位示例配置片段可以直接替换后使用。1. 先把异常堆栈读透MailConnectException 咬的是哪一段1.1 三层异常嵌套每一层都在告诉你不同的事JavaMailSender抛出的完整堆栈通常长这样注意从外到内读org.springframework.mail.MailSendException: Mail server connection failed; nested exception is com.sun.mail.util.MailConnectException: Could not connect to SMTP host: smtp.example.com, port: 465, response: -1最外层MailSendException是 Spring 的统一封装它本身不含信息量只说明“发送动作失败了”。真正有价值的是中间那层MailConnectException这是 JavaMail 实现里的连接异常它明确告诉你连接在TCP 建立或协议握手阶段就断了消息根本没有被投递出去。最后的response: -1是关键判据——-1表示客户端没有从服务端读到任何 SMTP 响应码。这里有个非常实用的判断技巧看 response 后面跟的是 -1 还是三位数字。如果是response: 535、550、553这类具体码说明 TCP 已经通了服务端也回了话问题在认证或发件人校验跟“连不上”是两回事如果永远是-1那才真的是链路层没打通或者握手失败。很多人被这条报错带偏一看到 “Could not connect” 就去改密码其实密码根本还没被送出去。另外要留意有没有MailAuthenticationException。Spring 把它和连接异常分开了认证失败会单独抛这个类型。但现实里有些邮件服务端在 TLS 握手失败或者 IP 被限制时会直接掐断连接客户端拿到的仍然是MailConnectException所以不能只靠异常类型下结论还是要结合 response 码和日志时间点判断。1.2 连接阶段、握手阶段、认证阶段三种失败长得像但根因完全不同我习惯把一次 SMTP 交互拆成三个时间窗口出问题先定位落在哪个窗口阶段典型耗时特征可能的异常优先怀疑TCP 三次握手一直卡到超时默认可能是无限MailConnectExceptionresponse: -1DNS、端口未放行、安全组、目标地址不可达TLS 握手卡住或几秒内断开MailConnectException / SSLHandshakeException 包装后端口与加密方式错配、证书链、容器缺 CA、系统时间认证与投递快速返回MailAuthenticationException 或 535/550用户名格式、授权码、发件人域名校验判断落在哪个窗口看两件事就够了日志里从发起请求到抛异常花了多久以及有没有出现SSLHandshakeException、PKIX path building failed这类被包在里面的 cause。卡满超时时间才抛大概率是 TCP 层没通一两秒就断往往是握手或服务端主动拒绝。这个判断能省掉一大半无效排查。我踩过的一个典型误判某次线上报错日志显示连接失败我第一反应是网络策略调整了结果翻完整堆栈发现最里层藏着java.security.cert.CertPathValidatorException。证书校验失败被 JavaMail 包成了连接异常光看外层那句话完全看不出来。所以永远要把Caused by链拉到底别只看第一行。2. 端口和加密方式错配这条报错最高频的来源2.1 25、465、587 三个端口握手方式根本不是一回事邮件提交端口的差异是这条报错最常见也最容易忽略的根因。三者的行为完全不同25 端口传统明文 SMTP先明文打招呼需要加密再通过 STARTTLS 命令升级。很多云主机默认限制出网 25 端口用来抑制垃圾邮件外发所以本地通、服务器不通是常态。465 端口隐式 SSL早年叫 SMTPSTCP 连上之后立刻开始 TLS 握手没有明文阶段。587 端口明文连接 STARTTLS 显式升级是现在主流的提交端口认证通常在升级之后进行。错配是怎么发生的举个最典型的配置写了 465但mail.smtp.ssl.enable没开。客户端连上 TCP 后按明文发EHLO而服务端在等 TLS ClientHello两边互相等最后客户端超时抛出来的就是Could not connect ... response: -1。反过来587 端口上把ssl.enable设成 true客户端直接发 ClientHello 打到明文端口服务端通常直接断开连接表现也是一两秒内失败。所以看到这条报错第一件事不是改密码是核对端口号与两个开关ssl.enable、starttls.enable是否成对。这三者必须作为一个整体来配拆开看没有意义。2.2 ssl.enable 和 starttls.enable 不是二选一语义完全不同很多人以为这两个开关是对立的其实它们控制的是两个不同的动作mail.smtp.ssl.enabletrue连接建立后立即启用 TLS适用于 465。mail.smtp.starttls.enabletrue先明文连接再发STARTTLS命令升级适用于 587 和 25。mail.smtp.starttls.requiredtrue升级失败就报错中止而不是降级为明文继续。第三个参数值得单独说。默认情况下starttls.enabletrue只是尝试升级如果服务端不支持某些实现会悄悄退回明文继续。这在生产环境是隐患所以走 587 时我一般把required也设为 true宁可失败也不要明文传输凭据。还有一个冷门但真实的坑个别服务端的 587 端口在 STARTTLS 之后才允许AUTH如果你把mail.smtp.auth关了会在握手成功后立刻收到530 Authentication required而某些客户端版本会把这个阶段的问题也包装成连接异常。所以auth参数也要一起确认。2.3 两套可以直接抄的配置模板465 隐式 SSL 的写法spring: mail: host: smtp.example.com port: 465 username: no-replyexample.com password: ${MAIL_AUTH_CODE} default-encoding: UTF-8 properties: mail: smtp: auth: true ssl: enable: true connectiontimeout: 5000 timeout: 5000 writetimeout: 5000587 STARTTLS 的写法spring: mail: host: smtp.example.com port: 587 username: no-replyexample.com password: ${MAIL_AUTH_CODE} default-encoding: UTF-8 properties: mail: smtp: auth: true starttls: enable: true required: true connectiontimeout: 5000 timeout: 5000 writetimeout: 5000注意username一般要写完整邮箱地址不是 前面那一截。有些服务端接受短名有些直接拒绝为了可移植性统一写全。密码位置放的是申请来的授权码/应用专用密码不是账号登录密码——这一点后面还会展开。敏感信息别硬编码进 yml。我一般的做法是通过环境变量注入本地开发用.env或者 IDE 的运行配置容器里用编排工具的密钥管理能力源码仓库里只留${MAIL_AUTH_CODE}这种占位符。这不是洁癖是防止某天仓库权限外泄时连带把发信能力一起送出去。3. 从应用主机出发把链路一段段掐断来验3.1 先确认解析结果再看它是不是你想要的那个地址报错里的 host 是应用自己解析出来的。如果 DNS 返回了多条记录客户端通常按顺序尝试第一条不通就超时根本轮不到第二条。先看解析getent hosts smtp.example.com # 或者 nslookup smtp.example.com 8.8.8.8重点看两件事有没有 AAAA 记录IPv6以及返回的地址是不是你能访问的那一组。容器环境里很常见的情况是——DNS 同时返回 IPv4 和 IPv6JVM 优先尝试 IPv6而宿主机的容器网络没有 IPv6 出口于是一路超时。表现就是有的机器能发、有的机器不能发非常迷惑。这种情况有两个处理方向一是给 JVM 加参数-Djava.net.preferIPv4Stacktrue强制走 IPv4二是干脆在容器网络层把 IPv6 关掉。我更倾向第一种改动小、可回滚。加参数后重启应用再发一封如果立刻通了基本可以确认是这个原因。还有一种低频情况解析到的是内网地址或者上一轮迁移遗留的旧地址。这时候连通性测试全通但那个地址上的 SMTP 服务根本不提供你需要的功能或者直接拒绝连接。所以测试前一定先打印解析结果别拿一个错误的目标去测。3.2 用命令行从目标机器上实测端口不要在本地测这一步是分水岭。很多人的排查方式是我本地用邮件客户端能发啊但应用跑在另一台机器上网络路径完全不同。必须登到应用所在的那台机器上去测。# 测 TCP 能不能通 timeout 5 bash -c cat /dev/null /dev/tcp/smtp.example.com/465 echo tcp ok || echo tcp fail # 或者用 nc nc -vz -w 5 smtp.example.com 465 # 测 TLS 握手和证书 openssl s_client -connect smtp.example.com:465 -servername smtp.example.com -briefopenssl s_client是排查这条报错最有价值的单条命令因为它一次给你三份信息TCP 是否可达、TLS 是否能协商成功、证书的签发者与有效期。如果它报connect: Connection timed out问题在网络层如果报verify error: unable to get local issuer certificate问题在信任链如果握手成功但证书notAfter已经过期那应用侧一定失败。顺手看一眼系统时间date -u时间偏差超过证书有效期容差通常几分钟到几十分钟校验就会失败。容器里时钟漂移不是稀罕事尤其是长期不重启的实例。这种情况报错文案和连不上几乎一样很容易被误判成网络问题。3.3 本地通、服务器不通出网策略与端口限制的典型形态这个场景我遇到过至少三次每次都是同一个套路开发环境在公司办公网25、465、587 全都放行生产环境在受限的云上网络出方向只开了 80 和 443邮件端口一律不通。区分方法很简单做对照实验测试项结果结论目标 465 端口 TCP 不通fail出网策略、安全组或目标侧限流目标 587 端口 TCP 通ok端口策略按端口粒度配置换端口可解目标 443 端口通比如访问任意 HTTPS 站点ok机器本身有正常出网能力排除整体断网同一目标从另一台机器测通ok问题定位在本机出网规则如果确认是出网策略限制处理方式无非两种申请放通对应端口或者换成服务商提供的、允许在已开放端口上提交的通道。这里不要抱侥幸心理去试各种旁路方案正规做法就是走网络策略变更流程同时在代码里做好失败兜底别让邮件发不出去把主业务流程拖垮。3.4 容器精简镜像缺根证书握手会失败得很像连不上用精简基础镜像构建的应用/etc/ssl/certs或者ca-certificates包经常是缺失的。表现是宿主机上openssl s_client一切正常容器里跑应用就报连接失败堆栈深处藏着PKIX path building failed或者unable to find valid certification path。验证方式是在容器里执行ls /etc/ssl/certs | head # 或者直接测 openssl s_client -connect smtp.example.com:465 -servername smtp.example.com如果容器里没有openssl命令那本身就是个信号——这个镜像太精简了。修复方式是在 Dockerfile 里补上证书包RUN apk add --no-cache ca-certificates update-ca-certificates # Debian 系 RUN apt-get update apt-get install -y --no-install-recommends ca-certificates企业内网如果有自建证书体系还需要把内部根证书导入 JVM 的信任库cacerts或者通过-Djavax.net.ssl.trustStore指定。这一步容易被跳过因为本地开发机通常装了一堆根证书什么问题都没有一进容器就炸。4. 配置看起来没问题却还是报错框架层的细节陷阱4.1 host 字段只填主机名别把协议和端口塞进去spring.mail.host期望的是纯主机名。我见过写成smtps://smtp.example.com的也见过写成smtp.example.com:465的。前者会导致 DNS 解析一个带协议头的字符串必然失败后者看起来合理但端口被拼进 host 之后实际连接的目标就变成了smtp.example.com:465:465这种畸形地址JavaMail 会直接抛连接异常。正确的做法是 host 和 port 分开写。这个坑的特征是报错里的 host 值明显带着冒号或斜杠。所以看日志时先核对报错里打印的 host 和 port 是不是你预期的值这一步能立刻排除掉一类低级但高频的错误。另外注意spring.mail.properties.mail.smtp.*这一层的路径。Spring Boot 会把spring.mail.properties下的所有键平铺成 JavaMail 的 Session 属性所以必须是mail.smtp.xxx开头少一层mail或者把smtp和ssl的顺序写错配置不会报错只是不生效——然后你就得到一条配置明明写了却没起作用的诡异现象。4.2 超时参数默认接近无限卡住时连日志都没有JavaMail 的三个超时属性默认值是无限等待这意味着网络不通时线程会一直挂着直到操作系统层面的 TCP 超时可能几分钟。表现出来就是发邮件的接口长时间无响应日志里没有任何异常最后要么被上游网关掐断要么线程池被拖满。三个参数的分工要搞清楚参数作用建议值mail.smtp.connectiontimeout建立 TCP 连接的等待时间3000~5000 msmail.smtp.timeout等待服务端响应的读超时5000~10000 msmail.smtp.writetimeout发送数据的写超时5000~10000 ms单位是毫秒值以字符串形式传入。三个都要设只设一个的话另外两个仍然是无限。我一般统一设 5 秒邮件这种非实时业务5 秒拿不到结果就当失败处理然后进补偿流程比让请求挂在那里好得多。设了超时之后还有个好处报错会变快你能立刻拿到异常并看到堆栈而不是等几分钟后从网关的 504 里反推。4.3 Spring Boot 版本升级带来的 javax / jakarta 分叉Spring Boot 3 开始邮件相关 API 从javax.mail迁移到了jakarta.mail。如果你升级了主框架版本但依赖没跟上或者反过来引了两个版本的 mail 实现会出现一类很迷惑的现象应用能启动注入正常但一调用发送就在连接阶段抛异常堆栈里往往伴随NoSuchMethodError或ClassNotFoundException。排查方式mvn dependency:tree -Dincludes*mail* # Gradle ./gradlew dependencies --configuration runtimeClasspath | grep -i mail确认jakarta.mail-api和具体实现如angus-mail版本一致且没有残留javax.mail的传递依赖。这一步在 Boot 2 升 3 的项目里几乎是必做的别指望编译器提醒你。4.4 认证失败有时也被伪装成连接失败前面说过要看 response 码这里补充几个常见混淆点密码位置填了登录密码而不是授权码。多数服务商在开启 SMTP 服务时会给一串独立的应用密码直接用账号密码认证会被拒。用户名没写全。no-reply和no-replyexample.com在不同服务端行为不一致。发件人地址与认证账号不一致。有些服务端要求From必须是认证账号或其别名否则投递阶段返回553。这个不属于连接问题但因为它发生在同一次调用的后半段日志混在一起容易看错。服务端对该来源 IP 做了限制。表现可能是握手后立刻断开客户端拿到的仍是连接异常。我一般的定位流程是先用openssl s_client确认握手能成再用一段最小化的 Java 代码单独跑认证把业务代码的干扰排除掉。最小化验证能跑通问题一定在配置或依赖跑不通问题在凭证或服务端策略。5. 几个真实项目里踩出来的坑5.1 连接池复用遇上中间设备静默断连JavaMail 默认每次发送新建连接但如果为了性能开了mail.smtp.connectionpooltrue就要面对连接被中间网络设备回收的问题。表现是服务刚启动时发送正常跑几个小时后开始零星报连接失败重启后又好一阵。这类问题的特征是失败率随运行时长上升且集中在低峰期后的第一次发送。原因是池里的连接在空闲时被链路上的设备清掉了但客户端不知道仍然拿旧连接去写数据写到一半才发现对端已经关闭。处理方式有两种一是关闭连接池接受每次建连的开销对低频发送完全够用二是保留连接池但把mail.smtp.timeout设小并在捕获到连接类异常时做一次销毁当前 sender、重建连接的重试。我倾向第一种邮件量不大的系统没必要为这点性能引入状态管理。5.2 异步发送把异常吞得干干净净用Async包装发送逻辑很常见目的是不阻塞主流程。问题在于异步方法里抛出的异常默认不会传播到调用方如果没配AsyncUncaughtExceptionHandler异常只会打一条日志甚至因为日志级别不够而彻底消失。结果就是业务侧显示发送成功因为方法是 void实际上邮件从来没出去。等用户投诉没收到验证码回头查日志才发现早就在报Could not connect。我的做法是异步方法返回CompletableFutureVoid或者干脆把发送结果落一张表状态流转为待发送 → 已提交 → 已成功/已失败失败带错误摘要。这样邮件问题变成可观测的业务数据而不是埋在日志里的异常。同时给AsyncConfigurer配上异常处理器保证任何漏网的异常都能进告警。5.3 把发信能力放在主链路上一次网络抖动就是一次故障这个不是技术坑是设计坑。早期有个项目用户注册接口里同步调发送邮件邮件服务一抖动注册接口跟着 500。后来改成注册只负责落库并投递一条消息独立的发送任务消费消息、带重试、失败进死信表人工兜底。改造之后有几个明显收益注册接口的 P99 不再受邮件服务影响发送失败可以按退避策略重试比如 1 分钟、5 分钟、30 分钟各一次重试次数用尽后进人工队列运营可以手动补发。这套结构对任何外部依赖都适用不只是邮件。6. 一套可复用的定位顺序与线上兜底设计6.1 五步定位法从最外层异常一路收敛到根因被这条报错卡住时我按下面这个顺序走基本能在十几分钟内收敛拉全堆栈确认 response 是 -1 还是三位码确认有没有SSLHandshakeException、PKIX之类的内层 cause。核对端口与加密开关的配对465 配ssl.enable587 配starttls.enable requiredhost 里不能带协议和端口。在应用所在机器上测连通性nc -vz测 TCPopenssl s_client测握手与证书date -u看系统时间。检查出网策略用不同端口做对照实验确认是端口级限制还是整体不通顺带确认 DNS 是否解析到了 IPv6 而容器没有 IPv6 出口。最后才怀疑凭证用最小化代码单独验证认证排除业务代码和依赖版本的干扰。这个顺序的价值在于从便宜的操作往贵的操作排前四步都是命令行几分钟能完成的最后一步要写代码、要申请凭证放最后。6.2 生产环境该有的兜底可重试与不可重试要分开不是所有失败都值得重试。判断标准很简单异常类型是否重试理由连接超时、握手超时是退避重试 2~3 次大概率是瞬时网络抖动认证失败535否凭证错了重试多少次都一样还会触发风控收件人不存在550否数据问题重试无意义服务端限流421/450是拉长间隔需要给对端缓冲时间实现上把异常按类型分流只对白名单内的异常走重试队列其余直接落失败表并告警。同时给整个发送环节加一个总开关出问题时能一键降级为只落库不发送避免故障期间把线程资源全耗在等待超时上。还有一个容易被忽略的点告警要带上下文。只报邮件发送失败没有意义要带 host、port、response 码、异常首行、失败次数的环比变化。有了这些值班的人不用登机器就能判断是配置问题还是网络问题。最后分享一个我自己一直在用的小习惯把上面那套openssl s_client、nc -vz、date -u写成一段脚本随应用镜像一起打包进去。下次再看到Could not connect to SMTP host在容器里跑一下脚本三十秒内就能知道是链路、证书还是时间的问题比翻文档快得多。这个脚本我前后改过几版现在连目标端口和是否走 STARTTLS 都能自动判断算是被这条报错逼出来的一点副产品。