jenkins邮件配置核心步骤与故障排查，看这篇就够了
Jenkins邮件配置要想一次跑通，关键不在填对SMTP服务器，而是把发送人地址、认证信息、全局的Extended E-mail Notification模板这三处同步配好。很多人设置了邮件通知却在构建时收不到任何信，问题多半出在系统管理员邮箱没填、或默认发件人后缀和登录账号不一致。
jenkins邮件配置失败？先从这三处下手
业内专家指出,绝大多数jenkins邮件配置失败案例都与”配置入口混淆”有关，Jenkins里能配邮件的地方不止一个，两个入口都设置完整，通知才能正常触发。
邮件通知与Extended E-mail Notification有何区别
老版Jenkins只有”邮件通知”一项，新版默认推荐的是Extended E-mail Notification（扩展邮件通知），入口路径如下：
- 邮件通知（基础版）：
Jenkins管理 → 系统配置 → 邮件通知 - Extended E-mail Notification（增强版）：
Jenkins管理 → 系统配置 → Extended E-mail Notification
两处都要填写SMTP信息，不能只配一处了事，扩展版负责构建结果邮件、内容模板、触发条件；基础版则起到兜底作用，发送系统级通知。
如何区分认证方式与端口对应关系
| SMTP服务商 | 端口（SSL） | 端口（STARTTLS） | 认证方式 |
|---|---|---|---|
| QQ邮箱 | 465 | 587 | 授权码登录 |
| 163邮箱 | 465 | 587 | 授权码登录 |
| Gmail | 465 | 587 | 应用专用密码 |
| 公司自建邮箱 | 视配置而定 | 视配置而定 | 域账号或LDAP |
填写SMTP端口时,465走SSL加密，587走STARTTLS，若Jenkins所在的JDK版本较低，部分服务商要求用465，否则会报SSL握手异常。
发件人地址为什么必须与登录账号完全一致
大多数新手配完后反复收到535 Authentication Failed，原因就是发件人地址填了别名，或者随意写了一个邮箱，而SMTP登录账号是另一个，行业共识认为，发件人地址就是SMTP认证身份，必须一字不差。
更为隐蔽的问题是：系统管理员邮件地址未填，该字段位于系统配置 → Jenkins Location → 系统管理员邮件地址，若这里为空，扩展邮件通知会直接丢弃邮件，而不会报错，表现就是构建成功了但邮件无声无息。
jenkins怎么配置邮件通知才算完整
配置流程分为四步,每一步都有可验证的判定标准，按顺序走一遍即可。
第一步：准备SMTP授权信息
以QQ邮箱为例,过程如下：
- 登录QQ邮箱网页端,进入
设置 → 帐户 - 找到POP3/IMAP/SMTP服务，开启IMAP/SMTP
- 按提示发送短信验证,获取16位授权码
- 记录授权码,在Jenkins中作为邮箱登录密码使用
对于163邮箱,支持客户端授权码后，同样用授权码而不是原密码。
公司内网邮箱的SMTP信息通常由IT部门提供,一般格式为smtp.company.com，端口依据加密方式变化，若不确定端口，可询问运维同事。
第二步：填写基础邮件通知区域
在Jenkins管理 → 系统配置页面，找到”邮件通知”模块：
- SMTP服务器：填写邮箱服务商给的地址，如
smtp.qq.com - 使用SMTP认证：勾选后填用户名和密码
- 用户名：完整邮箱地址（如
123456@qq.com） - 密码：授权码，不是邮箱密码
- 使用SSL协议：勾选（对应465端口，没勾选则对应587端口）
- 通过发送测试邮件测试配置：填一个测试接收邮箱后点击
若能收到测试邮件,说明基础配置已通，这一步直接影响后续扩展通知的发送。
第三步：填写Extended E-mail Notification区域
这是决定构建邮件内容质量的关键模块,需要逐项检查：
- 默认收件人：填写一个兜底接收邮箱（如团队负责人）
- 默认主题：建议写带项目名和构建状态的形式，如
[$BUILD_STATUS] $PROJECT_NAME - Build # $BUILD_NUMBER可引用预设变量，常用变量如下
构建邮件中可以嵌入的常见变量：
$PROJECT_NAME：项目名称$BUILD_NUMBER：构建序号$BUILD_STATUS：构建状态（SUCCESS/FAILURE等）$BUILD_URL：构建记录链接$GIT_COMMIT：Git提交版本号$CAUSE：构建触发原因（如”由用户XXX启动”）
填写完成后,点击页面底部保存，此时可到项目管理里触发一次构建做验证。
第四步：项目内单独配置收件人列表
全局配置只搭好了骨架,每个项目还需指定接收人，进入具体项目 → 配置 → 构建后操作，添加Editable Email Notification，按以下方式设置：
- 项目收件人列表：填该项目相关成员的邮箱，多个用逗号分隔
- 发送给构建者：勾选此项后，谁触发了构建就给谁发邮件
- 发送给提交者：有版本控制插件时，可自动通知最近提交代码的开发者
- 触发条件：勾选
构建失败、构建成功、不稳定等对应选项
这里有一个容易忽略的地方：“构建前”触发不要勾，会产生大量无效邮件干扰收件人，多数团队的合理配置是失败必须发、恢复成功时发。
jenkins邮件模板配置如何让团队不再忽略通知
一套好模板能减少群聊里的”谁看下构建怎么红了的”消息数量，模板不需要花哨，重点是把关键信息放在前三行。
常用的构建状态主题模板
针对不同状态的标题,比较实用的写法如下：
| 状态 | 主题模板示例 |
|---|---|
| 成功 | ✓ 构建成功：# $BUILD_NUMBER - $PROJECT_NAME |
| 失败 | ✗ 构建失败：# $BUILD_NUMBER - $PROJECT_NAME - 请立即检查 |
| 不稳定 | △ 构建不稳定：# $BUILD_NUMBER - $PROJECT_NAME（有测试未通过） |
不需要在主题里写过多信息,收件人扫一眼主题就知道是否需要点开，失败的构建邮件在QQ邮箱、企业微信、钉钉等推送到手机时，标题会直接显示，简洁反而高效。
自定义模板内容时保留哪些核心信息
建议按以下顺序排列信息：
- 项目名称与构建编号
- 构建结果与触发原因
- 构建版本（Git提交号或SVN版本号）
- 构建日志链接（将
$BUILD_URL转化为可点击链接） - 变更记录或提交信息摘要
- 测试结果摘要（有测试时）
常见的自定义模板写法可参考：
$PROJECT_NAME - Build # $BUILD_NUMBER - $BUILD_STATUS
查看详细构建信息：
$BUILD_URL
本次构建由：$CAUSE
代码版本：$GIT_COMMIT
控制台输出（尾部摘要）：
${BUILD_LOG, maxLines=50, escapeHtml=true}
收到该邮件说明构建状态有变化，请及时关注。若不知道变量怎么写,可先使用Jenkins默认模板，构建一次后再迭代调整正文格式。
排查jenkins邮件配置不生效时最实用的五步法
配置正确但收不到邮件,按顺序排查能快速定位：
- 查看构建日志中邮件相关片段,控制台输出中会出现
Email was triggered for:或Sending email for trigger:字样，若没出现说明触发条件没满足 - 检查构建后操作里是否选择了正确的响应触发器,很多情况下邮件不发送是因为
Always（总是）没勾选，而默认只有Failure被勾选 - 看Jenkins系统日志中有没有
MailException或AuthenticationFailedException，该日志位置在Jenkins管理 → 系统日志的All Jenkins Logs里 - 确认发件邮箱服务商的SMTP并发连接限制,部分免费邮箱限制每小时发送量，频繁构建时报
Too many connections
- 用telnet或命令行直测SMTP服务连通性,在Jenkins服务器上执行
telnet smtp.qq.com 465，无法连接则是网络防火墙拦截
让人困惑的Timeout异常到底是什么含义
SMTP超时通常有两个含义：一是Jenkins服务器连不上SMTP服务商`，二则是SMTP服务商认为该会话闲置时间过长。
许多公司内网服务器访问外网邮箱需要配置HTTP代理,而且Java环境变量-Dhttp.proxyHost不会自动生效，若本机命令行测试SMTP正常，但Jenkins始终超时，可尝试在Jenkins启动参数中添加-Dmail.smtp.connectiontimeout=60000 -Dmail.smtp.timeout=60000，以此放宽网络延迟容忍度。
测试邮件成功，但构建后邮件只发给一部分人
这种现象大多与项目的默认收件人和全局默认收件人的叠加逻辑有关，全局配置中填写了兜底邮箱，项目内又配置了项目收件人，扩展邮件通知会把两处收件人合并发送，若项目内没有填写任何收件人，系统只会按全局默认收件人发。
若想完全按项目自有的收件名单发送,需要清空全局默认收件人，在项目内逐个配置。
Q&A：关于jenkins邮件配置的常见疑问
使用QQ邮箱配置Jenkins，总是报535错误，这是账号密码不对吗
535错误的直接原因是SMTP认证失败,除了授权码抄写错误外，更容易忽略的情况是：发件人地址中的域名部分必须与登录邮箱一致，例如使用foxmail域名但登录了QQ邮箱，就会触发535，授权码中有空格或特殊字符被复制不完整的情况也较为常见，建议重新生成授权码并粘贴后去掉首尾空格做测试。
怎么判断Jenkins应该用SSL还是普通端口
SSL端口与STARTTLS端口的主要区别在于TLS握手时机,若SMTP服务商明确提供465端口，优先选择SSL方式；若公司内网邮箱只开放25端口，则不勾选SSL，同时该场景需要将mail.smtp.starttls.enable参数设置为true，个别定制化内网系统同时要求自定义mail.smtp.socketFactory.class取值，此时需咨询邮件系统管理员确认具体参数。
构建失败的邮件偶尔收到偶尔收不到，最可能是什么问题
最常见的原因是触发条件重复勾选导致逻辑冲突,比如同一封邮件被多个触发器匹配时，部分版本的扩展邮件插件会判定为重复事件而丢弃，下游项目触发上游构建的场景下，若下游项目没有执行构建后操作，则邮件根本不会生成，此时应将触发条件精简为Failure和Fixed两项，并确认下游项目继承或独立配置了邮件规则，构造后行为需要逐项目检查生效范围。