邮件发送这个功能，很多项目在开发阶段就跑通了，上线之后却突然开始抛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 三次握手 | 一直卡到超时（默认可能是无限） | MailConnectException，response: -1 | DNS、端口未放行、安全组、目标地址不可达 |
| 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（早年叫 SMTPS），TCP 连上之后立刻开始 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.enable=true：连接建立后立即启用 TLS，适用于 465。mail.smtp.starttls.enable=true：先明文连接，再发STARTTLS命令升级，适用于 587 和 25。mail.smtp.starttls.required=true：升级失败就报错中止，而不是降级为明文继续。
第三个参数值得单独说。默认情况下starttls.enable=true只是"尝试升级"，如果服务端不支持，某些实现会悄悄退回明文继续。这在生产环境是隐患，所以走 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-reply@example.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-reply@example.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 和 IPv6，JVM 优先尝试 IPv6，而宿主机的容器网络没有 IPv6 出口，于是一路超时。表现就是"有的机器能发、有的机器不能发"，非常迷惑。
这种情况有两个处理方向：一是给 JVM 加参数-Djava.net.preferIPv4Stack=true强制走 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 ms |
mail.smtp.timeout | 等待服务端响应的读超时 | 5000~10000 ms |
mail.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-reply@example.com在不同服务端行为不一致。 - 发件人地址与认证账号不一致。有些服务端要求
From必须是认证账号或其别名，否则投递阶段返回553。这个不属于连接问题，但因为它发生在同一次调用的后半段，日志混在一起容易看错。 - 服务端对该来源 IP 做了限制。表现可能是握手后立刻断开，客户端拿到的仍是连接异常。
我一般的定位流程是：先用openssl s_client确认握手能成，再用一段最小化的 Java 代码单独跑认证，把业务代码的干扰排除掉。最小化验证能跑通，问题一定在配置或依赖；跑不通，问题在凭证或服务端策略。
5. 几个真实项目里踩出来的坑
5.1 连接池复用遇上中间设备静默断连
JavaMail 默认每次发送新建连接，但如果为了性能开了mail.smtp.connectionpool=true，就要面对连接被中间网络设备回收的问题。表现是：服务刚启动时发送正常，跑几个小时后开始零星报连接失败，重启后又好一阵。
这类问题的特征是失败率随运行时长上升，且集中在低峰期后的第一次发送。原因是池里的连接在空闲时被链路上的设备清掉了，但客户端不知道，仍然拿旧连接去写数据，写到一半才发现对端已经关闭。
处理方式有两种：一是关闭连接池，接受每次建连的开销（对低频发送完全够用）；二是保留连接池但把mail.smtp.timeout设小，并在捕获到连接类异常时做一次"销毁当前 sender、重建连接"的重试。我倾向第一种，邮件量不大的系统没必要为这点性能引入状态管理。
5.2 异步发送把异常吞得干干净净
用@Async包装发送逻辑很常见，目的是不阻塞主流程。问题在于，异步方法里抛出的异常默认不会传播到调用方，如果没配AsyncUncaughtExceptionHandler，异常只会打一条日志，甚至因为日志级别不够而彻底消失。
结果就是：业务侧显示"发送成功"（因为方法是 void），实际上邮件从来没出去。等用户投诉没收到验证码，回头查日志才发现早就在报Could not connect。
我的做法是异步方法返回CompletableFuture<Void>或者干脆把发送结果落一张表，状态流转为"待发送 → 已提交 → 已成功/已失败"，失败带错误摘要。这样邮件问题变成可观测的业务数据，而不是埋在日志里的异常。同时给AsyncConfigurer配上异常处理器，保证任何漏网的异常都能进告警。
5.3 把发信能力放在主链路上，一次网络抖动就是一次故障
这个不是技术坑，是设计坑。早期有个项目，用户注册接口里同步调发送邮件，邮件服务一抖动，注册接口跟着 500。后来改成：注册只负责落库并投递一条消息，独立的发送任务消费消息、带重试、失败进死信表人工兜底。
改造之后有几个明显收益：注册接口的 P99 不再受邮件服务影响；发送失败可以按退避策略重试（比如 1 分钟、5 分钟、30 分钟各一次）；重试次数用尽后进人工队列，运营可以手动补发。这套结构对任何外部依赖都适用，不只是邮件。
6. 一套可复用的定位顺序与线上兜底设计
6.1 五步定位法，从最外层异常一路收敛到根因
被这条报错卡住时，我按下面这个顺序走，基本能在十几分钟内收敛：
- 拉全堆栈，确认 response 是 -1 还是三位码，确认有没有
SSLHandshakeException、PKIX之类的内层 cause。 - 核对端口与加密开关的配对，465 配
ssl.enable，587 配starttls.enable + required，host 里不能带协议和端口。 - 在应用所在机器上测连通性，
nc -vz测 TCP，openssl 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 都能自动判断，算是被这条报错逼出来的一点副产品。
