做持续集成的同学应该都有同感构建跑完没人看就跟没跑一样。任务挂在 Jenkins 上绿了、红了、黄了全靠人肉刷新页面开发提测了问一句这次构建过了吗运维发布前又问一句最新包是哪次构建出的整个环节全靠人在中间传话。我做过好几套构建流水线最后都无一例外地把邮件通知加上去了——不是它多炫而是它便宜、通用、不依赖任何 IM 群或网页状态构建一旦结束结果自动推给该知道的人。这一篇就专门讲怎么在 Jenkins 里把构建并发送邮件这件事做扎实从插件选型、SMTP 配置、触发规则到邮件模板定制、常见坑排查全部按实操顺序来。这套方案不挑场景。个人维护的小项目可以用团队跑自动化测试的流水线可以用连对接测试报告、产物归档的正式发布流程也能用。我会把每一步的参数、写法、背后的为什么一起讲清楚你照着配一遍基本一小时内能跑通。1. 为什么要在 Jenkins 里做构建邮件先搞清楚这个环节在解决什么问题1.1 构建结果的传递不该靠人工很多团队一开始没有邮件通知觉得 Jenkins 页面上状态写得很清楚谁要看谁自己上去看。但实际做下来就会发现这个假设非常脆弱。构建结果是一个典型的异步事件它什么时候结束没人能预知而你不可能让所有相关的人都在页面上死等。我见过最典型的场景是凌晨跑的回归测试挂了一整夜第二天早上开发来了才发现一上午的时间已经浪费掉了。邮件解决的就是这个构建完成但无人知晓的时间差。它有几个天然优势第一不需要构建者在线邮件是异步的收件人什么时候看都行第二覆盖面广不管是内部开发、测试、运维还是外包团队、跨部门协作邮箱是人人都有的基础工具不需要额外拉群、加账号第三有记录邮件的发件时间、内容、附件都可以留痕后面追溯构建历史、定位问题非常方便。我遇到过一种反对意见说我们已经在用即时通讯工具了机器人推消息不是更方便吗对IM 通知确实更实时但它要求所有相关人都必须在群里新人忘加群、外部协作方不在群、临时参与的人没有权限这些问题都很现实。邮件的定位是兜底通知渠道它和 IM 通知不冲突是一个互补关系。构建成功可以只在 IM 里说一声构建失败、不稳定这种需要重点关注的事件邮件是更稳妥的触达方式。1.2 邮件通知的两种主流方案怎么选Jenkins 发邮件过去常用的办法有两个一个是系统自带的邮件通知E-mail Notification在系统配置页面填上 SMTP 信息然后在任务里勾选构建后操作添加邮件通知就能发另一个是安装 Email Extension 插件也常被叫 Email-ext它扩展了邮件通知的能力支持丰富的触发条件、HTML 模板、附件、按角色分发等功能。对一个还没配过的项目我建议直接选 Email Extension不要犹豫。为什么因为内置邮件通知看着简单限制却非常明显它的邮件内容格式基本固定成功和失败只有一个主题行差异触发规则很粗只能做到每次构建都发或者失败才发想附带构建日志、测试报告内置功能基本做不到。而 Email Extension 可以做到按结果状态分别设置主题、按需附带日志和报告、用变量拼出动态内容配置好之后基本不用再动。当然内置邮件通知也有它的适用场景临时验证 SMTP 通不通、或者你只需要在某个老项目里极简地失败时喊一嗓子用它确实更快。但从长期维护的角度看装好插件、统一用一套模板比后面需求变了再迁移要省事得多。我一开始用内置通知等要加测试报告附件的时候还得回头重新配置一遍纯属重复劳动。2. 配置前必须做好的几项准备2.1 搞清 SMTP 服务器、端口和授权码的关系邮件要从 Jenkins 发出去本质上就是 Jenkins 作为邮件客户端通过 SMTP 协议把信交给邮件服务器再由邮件服务器投递给目标邮箱。所以配置的第一步是拿到发件邮箱的 SMTP 信息。这里有个容易被绕晕的点发件邮箱不是收件邮箱。你需要先准备一个专门用来发通知的邮箱账号然后用它自己的 SMTP 服务。我见过有人拿自己的私人邮箱当发件人结果授权码配错、被服务商限制、甚至把私人邮箱发爆完全不值得。正规做法是申请一个专用的通知邮箱比如通知机器人这种定位所有构建邮件都从它发出。SMTP 信息通常包含三样东西服务器地址、端口、安全方式。不同邮箱服务商的地址格式不一样一般形如邮件的服务商域名前缀加 smtp比如 smtp.某服务商.com 这种。端口常见的是 465 和 587465 对应 SSL 隐式加密587 对应 STARTTLS 显式加密还有老旧的 25 端口现在基本被各大服务商封掉不建议用。配的时候到底选哪个以你邮箱服务商官方文档里的推荐为准我自己的经验是优先 465配置简单、失败率低。还有一个关键点就是授权码。现在主流邮箱服务商都不再支持直接用登录密码做 SMTP 认证而是要求在网页端开启SMTP 服务并生成一个独立的授权码授权码和登录密码是两码事。很多新手第一次配置失败九成是因为拿登录密码去填了密码字段。这个东西有效期也需要注意有些服务商授权码长期有效有些会定期过期过期之后 Jenkins 那边就会开始报认证失败后面排查部分会再展开讲。2.2 系统管理里的两处邮件配置是新手最容易漏的Jenkins 里的邮件配置入口多这是很多人踩坑的根源。在 Manage Jenkins系统管理页面的 System系统配置里向下滚动能看到两个长得挺像的区域一个是E-mail Notification邮件通知对应内置邮件发送另一个是Extended E-mail Notification扩展邮件通知对应 Email Extension 插件。两个区域的字段几乎一样都是填 SMTP 服务器、默认后缀、用户名、密码。问题是你填了一个不代表另一个生效。如果你在任务的构建后操作里添加的是 Email-ext 的可编辑邮件通知那它走的是 Extended E-mail Notification 的配置如果你用内置的邮件通知走的是 E-mail Notification 的配置。两者内容不互通各填各的。我建议的做法是两处都老老实实填一遍相同的 SMTP 信息。虽然多费两分钟但能避免唉我明明配了啊这种排查半天的尴尬。另外Jenkins 在 Extended E-mail Notification 下面会有一个通过发送测试邮件测试配置的按钮可以填一个测试收件地址点一下验证 SMTP 是否连通。这个测试按钮能帮你确认基础链路通不通但它只是发一封固定内容邮件不等同于任务里的自定义模板和触发规则都能正常跑后面还得在任务里再验证一次。3. 实操配置让一次构建自动发出一封结果邮件3.1 安装 Email Extension 插件并确认系统设置第一步在 Manage Jenkins 的 Plugins插件管理页面里搜索 Email Extension安装后重启 Jenkins。插件名完整一点是 Email Extension Plugin安装完之后系统配置区域才会出现 Extended E-mail Notification。然后回到系统配置把两处 SMTP 都填好。我给一个参考配置注意用你自己环境的值替换配置项推荐值说明SMTP server你的邮箱服务商SMTP地址不要填网页登录地址Default user e-mail suffix你的域名用于给不带后缀的用户名自动补全邮箱Use SSL勾选对应 465 端口SMTP Port465 或 587取决于你的邮箱服务商推荐Reply-to Address通知邮箱地址方便收件人直接回复到通知邮箱CharsetUTF-8避免中文邮件乱码认证Credentials添加全局凭据用户名授权码别直接在Password字段填明文密码这里特别强调一下凭据的问题。老版本 Jenkins 是直接在配置页里填用户名/密码两个字段的新版本推荐在凭据里创建一条Username with password类型的全局凭据然后在 SMTP 认证里选择这条凭据。好处是凭据被加密存储配置页也支持不同环境复用团队里其他人操作时不用看到密码。我见过直接写在配置里的Jenkins 页面本身有权限控制还好但一旦配置页截图流出就非常被动所以能走凭据就走凭据。填完之后在 Extended E-mail Notification 页面底部先用发送测试邮件按钮验证一遍。如果报错检查服务器地址、端口、授权码三个字段挨个排除。测试邮件能收到说明基础链路已经通了。3.2 在流水线任务里接入邮件发送逻辑邮件配置好之后剩下的就是让构建任务在合适的时机触发邮件。有两种接入方式一种是在自由风格任务的构建后操作里可视化配置另一种是在流水线脚本里用emailext步骤调用。我个人更推荐流水线方式它把逻辑写在代码里模板、收件人、条件都跟任务定义一起版本化后面改起来清楚。用声明式流水线一个最小可用的发送逻辑长这样pipeline { agent any stages { stage(构建) { steps { echo 开始构建... // 这里替换成你真实的构建命令 sh ./build.sh } } } post { always { emailext( to: devexample.com, subject: 构建结果${env.JOB_NAME} #${env.BUILD_NUMBER} - ${currentBuild.currentResult}, body: p项目${env.JOB_NAME}/p p构建编号#${env.BUILD_NUMBER}/p p构建结果${currentBuild.currentResult}/p p构建地址a href${env.BUILD_URL}${env.BUILD_URL}/a/p p变更说明${env.CHANGE_LOG}/p ) } } }这段代码的意思很简单post { always { ... } }表示不管构建是成功、失败还是不稳定都会执行里面的步骤emailext是 Email Extension 插件提供的步骤to指定收件人subject是主题body是邮件正文。里面的${env.JOB_NAME}、${env.BUILD_NUMBER}这类是 Jenkins 的环境变量构建时会被替换成实际值currentBuild.currentResult是当前构建的结果状态。实际用下来我有几个注意点想说。第一收件人不要用recipientProviders那种花哨的动态分发先把to写死确认能收到后再按需调整第二post里的always会在每次构建都发邮件如果项目构建频率高邮件会很吵后面第 3.3 节专门讲触发规则的调整第三正文里最好带上构建地址的链接很多人收到邮件第一反应是点进去看控制台输出没有链接等于让收件人自己去 Jenkins 里找项目。如果你的任务用的是图形化界面不写脚本那就在构建后操作里添加可编辑邮件通知然后在配置界面设置收件人、主题、正文模板效果是一样的只是没有代码版本化那么方便。3.3 触发器怎么设置才不会被邮件轰炸邮件通知最让人反感的场景就是构建很频繁邮件跟机关枪一样扫射几天之后所有人设置了收件规则你的通知就等于白搞了。所以触发规则才是这套配置里真正需要认真思考的部分。Email Extension 插件支持很多触发条件最常用的有如下几个触发条件触发时机适合场景Always每次构建结束无论结果如何低频率、高关注度的构建比如发布包构建Failure仅构建失败时常规开发构建避免平时太多干扰Success仅构建成功时配合 Always 做失败、恢复双通知Unstable仅构建不稳定时测试有失败但未中断测试任务用于收集测试失败信息Change Failure上次成功、这次失败时才发减少连续失败时反复发信的噪音我自己的默认组合是Failure必发Unstable必发Success只在任务从失败转为成功时发一次——这个效果用Change Failure配对再配一个Change Success如果插件版本支持也能实现。核心思路是失败要知道恢复也要知道但别每次成功都刷一遍存在感。触发规则和post块怎么配合在声明式流水线里你可以按状态分别写post { failure { emailext( to: devexample.com, subject: 构建失败${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 见 Jenkins 构建页${env.BUILD_URL} ) } unstable { emailext( to: devexample.com, subject: 构建不稳定${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 测试有失败项见${env.BUILD_URL} ) } success { emailext( to: devexample.com, subject: 构建已恢复${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 上一次失败的构建已恢复见${env.BUILD_URL} ) } }这么写的好处是逻辑清楚失败、不稳定、恢复成功各走一支主题行一眼就能看出状态不需要在邮件正文里猜。我在实践中发现主题行把状态写到最前面非常有效尤其是手机端收邮件的时候通知栏里直接能看到构建失败四个字比点进去看正文强多了。4. 邮件内容高级定制把构建信息一次性讲清楚4.1 不要只发一行字用变量和模板把信息补全很多团队的 Jenkins 邮件开头是构建完成没了。这种邮件提供的信息量接近零收件人还得登录 Jenkins 去查。我们配置邮件目标应该是让收件人在收件箱里就完成 70% 的信息判断构建结果是什么、哪个项目、第几次构建、代码变更有哪些、测试结果如何、去哪里看详情。Email Extension 支持在主题和正文里使用变量。除了前面用到的$BUILD_NUMBER、$JOB_NAME、$BUILD_URL常用的还有这些变量含义$BUILD_STATUS构建结果状态SUCCESS/FAILURE/UNSTABLE/ABORTED$PROJECT_NAME任务名称$BUILD_URL本次构建的绝对地址$CAUSE触发本次构建的原因时间触发、手动触发、代码变更触发$CHANGELOG本次构建涉及的代码变更记录$TEST_COUNTS测试统计信息若测试任务有输出$BUILD_LOG_EXCERPT构建日志的摘要片段比如主题行可以写成这样[$BUILD_STATUS] $PROJECT_NAME 构建 #$BUILD_NUMBER - 变更:$CHANGELOG正文用一个简单的 HTML 模板把上面几个变量组织成清单收件人扫一眼就知道情况。Email Extension 也支持引用一个.jelly模板文件走Default Content区域直接编写 HTML 就行。我一般会加几行简单的 CSS 样式把失败状态标红、成功标绿判断依据还是$BUILD_STATUS变量模板会自动替换。这里提个醒HTML 模板里尽量别用过于复杂的 CSS有些邮件客户端会把样式剥掉越朴素兼容性越好。4.2 把测试报告和构建日志做成附件信息密度再翻一倍邮件正文写清楚了状态但很多场景下收件人还需要看细节。比如测试任务失败了你得知道是哪个用例挂的构建任务失败了你得知道是哪一步报错。这些信息靠人工去 Jenkins 页面里翻很费劲高效率的做法是让邮件带上附件。Email Extension 的attachLog参数可以控制是否把完整构建日志作为附件attachments参数可以指定附件路径。看一个带测试报告的例子post { failure { emailext( to: devexample.com, subject: 构建失败${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 详见附件和 Jenkins 地址${env.BUILD_URL}, attachLog: true, attachments: target/surefire-reports/*.txt ) } }attachLog: true会把整个控制台日志打包进去省得收件人去页面上翻日志面板。attachments是相对于 workspace 的路径支持通配符比如target/surefire-reports/*.txt就能把测试报告全部附上。如果你用的是 HTML 报告注意有些邮箱客户端会阻止 HTML 附件改成压缩包.zip更稳妥。附件不是越多越好。我踩过一个大坑某个项目构建日志动辄几十兆测试报告也很占空间结果邮件发不出去或者发到对方邮箱直接被系统退回。很多邮件服务商对单封邮件附件大小有限制一般在 10MB 到 25MB 之间。所以现在我的做法是默认不附全量日志只在构建失败时附日志摘要测试报告如果太大先归档成压缩包再附。日志本身也可以考虑在流水线里用tee只保留末尾几十行作为摘要文件再把这个摘要文件附上。4.3 用主题前置判断给邮件分档成功、失败、不稳定各自一套文案邮件内容其实也是可以分状态的。与其一封邮件里既要提成功又要提失败不如通过 Groovy 脚本判断当前结果动态拼出不同的主题和正文。这里的思路是把邮件当成一个状态卡片来做成功卡片告诉你可以安心失败卡片告诉你看哪里不稳定卡片告诉你测试有杂音但不影响发布决策。实现方式也不复杂在emailext步骤之前先算好变量。比如script { if (currentBuild.currentResult SUCCESS) { emailSubject [成功] ${env.JOB_NAME} #${env.BUILD_NUMBER} emailBody 构建已通过产物可下载${env.BUILD_URL} emailTo devexample.com } else if (currentBuild.currentResult UNSTABLE) { emailSubject [不稳定] ${env.JOB_NAME} #${env.BUILD_NUMBER} emailBody 存在测试失败用例请尽快处理。详情${env.BUILD_URL} emailTo devexample.com } else { emailSubject [失败] ${env.JOB_NAME} #${env.BUILD_NUMBER} emailBody 构建失败存在阻断问题请立即跟进。日志${env.BUILD_URL} emailTo devexample.com } emailext(to: emailTo, subject: emailSubject, body: emailBody) }这种方式适合收件人组比较固定的场景。如果你的收件人还要按状态区分比如失败时除了开发还要抄送测试、成功时不抄送那就在每个分支里单独设置emailTo。把发送动作也拆到各分支里去写逻辑会更直观一些。一套稳定跑了一年多的项目我现在基本就这么处理成功邮件发给提测群和产物负责人失败邮件额外抄送项目经理附件只在失败时带。这套规则稳定之后团队里几乎没人会漏看构建问题邮件里该有的信息都在任何人接手都能快速定位。5. 发不出去、收不到、进垃圾箱常见问题与排查技巧实录5.1 一张表解决 80% 的邮件问题邮件配置里踩过的坑归纳起来就那么几类。下面这个速查表基本覆盖了绝大部分场景。现象常见原因排查方法系统设置测试邮件失败SMTP地址/端口/认证信息错误检查服务器地址、端口、授权码三步逐个替换再重发测试邮件成功但任务不发任务没配置发信逻辑或配置在错误的区域确认任务配置走的内置邮件还是扩展邮件与系统配置对应构建日志显示发送成功但收不到被收件方反垃圾策略拦截检查垃圾箱、白名单加发件地址、调整发件频率收到邮件但中文乱码字符集未设置或模板编码不对系统配置和邮件模板里都设置为 UTF-8邮件没带附件路径写错或通配符没匹配到文件到 workspace 下确认文件实际存在路径先写死文件名测试发件人被退回授权码过期或发件频繁被限流重新生成授权码降低通知频率收件人收到多个重复邮件同时配置了多个触发器和构建后操作检查任务里是否有重复的邮件步骤保留一个发送逻辑这张表背后有一个通用排查思路先区分是发送没执行还是发出去了没收到。前者去 Jenkins 控制台日志里看邮件步骤的执行记录后者去检查收件方邮箱的反垃圾规则。很多新手在收到未送达退信时第一反应是改代码里的邮件内容其实退信内容里通常会写明失败原因比如邮箱地址不存在、附件过大、发件人被拒先读退信能省很多时间。5.2 几个容易忽略的坑第一个坑是时区和时间显示。Jenkins 服务器默认时区不一定是你的本地时区邮件里如果直接打印构建时间戳收件人看到的可能是 UTC 时间比北京时间早 8 小时。解决方法是给 Jenkins 服务设置正确的时区或者在邮件模板里先用new Date().format(...)这类 Groovy 代码格式化时区后再输出。我自己一开始没注意测试报告跑完凌晨两点邮件显示前一天下午六点排查问题时对时间对不上号非常误导。第二个坑是凭据过期。很多服务商生成的 SMTP 授权码不是永久有效的过期后 Jenkins 发送邮件会报 535 认证失败之类错误。这个故障特点是前两天还能发今天突然不行了。我遇到过一次当时差点以为是邮箱服务商故障后来登录邮箱后台一看授权码过期提示重新生成一个新授权码更新到凭据里就好了。建议在日历里给授权码到期时间做个提醒免得到时候抓瞎。第三个坑是发送频率限制。通知邮箱如果短时间内发了太多邮件比如一个异常循环导致构建任务反复触发邮件服务商会临时封禁发件账号表现为发送报错或者发出去全部进垃圾箱。这类问题要根治源头检查触发器是不是设置了每两分钟就跑且每次必发把触发频率降下来同时给emailext步骤外层加一个状态判断确保只有任务状态变化时才发从源头减少邮件数量。第四个坑是自建邮箱服务器的情况。如果你的团队用自建邮件系统除了要配好 SMTP 之外还要确认 Jenkins 服务器的 IP 有没有被收件方邮箱列入黑名单以及域名有没有配好 SPF/DKIM 记录。这类问题在公共邮箱之间不太常见但在企业邮箱互发时经常出现表现为我们内部互相发没问题但外部邮箱收不到。处理方式一般就两条自建服务器的做好反垃圾认证记录或者直接用公共邮箱服务代发。5.3 用控制台日志和调试模式定位邮件连接问题当邮件完全没发出去第一现场不是邮箱后台而是 Jenkins 任务的控制台输出。构建执行到emailext步骤时它会打印相关日志比如发送邮件给 xxxexample.com、邮件发送成功/失败之类。有时候报错信息里会直接给出 SMTP 的错误码比如 535 表示认证失败、550 表示收件地址被拒、552 表示附件过大这些错误码配合速查表就能快速定位。如果日志信息不够还可以把邮件相关日志级别调到最详细。Jenkins 的系统配置里Extended E-mail Notification 区域有一个启用调试模式的选项勾上后会在构建日志里输出完整的 SMTP 会话记录能看到客户端发送的每一行命令和服务器返回的结果。这个模式对排查握手成功但认证失败连接被关闭这类底层问题很有用。我一般不出问题不开因为信息量太大正常任务日志会被淹没。另外一个笨但有效的方法是 telnet 到 SMTP 端口手动测连通性telnet smtp.example.com 465如果端口能通说明网络链路没问题如果超时或被拒绝就要检查服务器防火墙、安全组规则或者是不是端口选错了。这条对自建 Jenkins 服务器尤其重要因为很多公司内网服务器对外网 465/587 端口访问是受限的得先让网络管理员放通。6. 最后再说一点我个人折腾下来的心得构建邮件这套东西单看每个配置点都不复杂但它确实是把构建完成这件事从信息孤岛变成信息闭环的关键一步。我现在维护的流水线里邮件已经是标配但我会刻意控制邮件的数量和信息密度失败必发、恢复必发、不稳定分情况发、成功极高价值时才发邮件内容里永远有结果、编号、链接、变更、日志/报告这五个要素一份模板反复用在所有任务上。有几个小建议你可以直接用第一第一次配置时先用一次性测试任务验证整条链路别直接在正式的发布流水线上试不然手抖配错了几十封邮件直接轰炸所有人第二收件人地址里的默认后缀补全功能区分一下用户名和完整邮箱很多人填错只差一个 后缀导致半天收不到第三给通知邮箱单独建一个联系人分组比如构建通知组新人入职直接加组比邮件里每次写一堆收件人省事得多。如果你现在跑的项目还没有邮件通知我建议别只在系统配置里点个测试邮件就完事还是老老实实按这篇的思路把触发规则、模板、附件设计好一次性配到位。这套活儿熟练之后半小时内就能搞完但它省下来的等人发现构建挂了的时间远远超出你这半小时的付出。后面如果要用到更复杂的场景比如多分支流水线按分支路由邮件、对接定时报告、按团队自定义模板也都是在这个基础上扩展基础打好了就都不难。
做持续集成的同学应该都有同感构建跑完没人看就跟没跑一样。任务挂在 Jenkins 上绿了、红了、黄了全靠人肉刷新页面开发提测了问一句这次构建过了吗运维发布前又问一句最新包是哪次构建出的整个环节全靠人在中间传话。我做过好几套构建流水线最后都无一例外地把邮件通知加上去了——不是它多炫而是它便宜、通用、不依赖任何 IM 群或网页状态构建一旦结束结果自动推给该知道的人。这一篇就专门讲怎么在 Jenkins 里把构建并发送邮件这件事做扎实从插件选型、SMTP 配置、触发规则到邮件模板定制、常见坑排查全部按实操顺序来。这套方案不挑场景。个人维护的小项目可以用团队跑自动化测试的流水线可以用连对接测试报告、产物归档的正式发布流程也能用。我会把每一步的参数、写法、背后的为什么一起讲清楚你照着配一遍基本一小时内能跑通。1. 为什么要在 Jenkins 里做构建邮件先搞清楚这个环节在解决什么问题1.1 构建结果的传递不该靠人工很多团队一开始没有邮件通知觉得 Jenkins 页面上状态写得很清楚谁要看谁自己上去看。但实际做下来就会发现这个假设非常脆弱。构建结果是一个典型的异步事件它什么时候结束没人能预知而你不可能让所有相关的人都在页面上死等。我见过最典型的场景是凌晨跑的回归测试挂了一整夜第二天早上开发来了才发现一上午的时间已经浪费掉了。邮件解决的就是这个构建完成但无人知晓的时间差。它有几个天然优势第一不需要构建者在线邮件是异步的收件人什么时候看都行第二覆盖面广不管是内部开发、测试、运维还是外包团队、跨部门协作邮箱是人人都有的基础工具不需要额外拉群、加账号第三有记录邮件的发件时间、内容、附件都可以留痕后面追溯构建历史、定位问题非常方便。我遇到过一种反对意见说我们已经在用即时通讯工具了机器人推消息不是更方便吗对IM 通知确实更实时但它要求所有相关人都必须在群里新人忘加群、外部协作方不在群、临时参与的人没有权限这些问题都很现实。邮件的定位是兜底通知渠道它和 IM 通知不冲突是一个互补关系。构建成功可以只在 IM 里说一声构建失败、不稳定这种需要重点关注的事件邮件是更稳妥的触达方式。1.2 邮件通知的两种主流方案怎么选Jenkins 发邮件过去常用的办法有两个一个是系统自带的邮件通知E-mail Notification在系统配置页面填上 SMTP 信息然后在任务里勾选构建后操作添加邮件通知就能发另一个是安装 Email Extension 插件也常被叫 Email-ext它扩展了邮件通知的能力支持丰富的触发条件、HTML 模板、附件、按角色分发等功能。对一个还没配过的项目我建议直接选 Email Extension不要犹豫。为什么因为内置邮件通知看着简单限制却非常明显它的邮件内容格式基本固定成功和失败只有一个主题行差异触发规则很粗只能做到每次构建都发或者失败才发想附带构建日志、测试报告内置功能基本做不到。而 Email Extension 可以做到按结果状态分别设置主题、按需附带日志和报告、用变量拼出动态内容配置好之后基本不用再动。当然内置邮件通知也有它的适用场景临时验证 SMTP 通不通、或者你只需要在某个老项目里极简地失败时喊一嗓子用它确实更快。但从长期维护的角度看装好插件、统一用一套模板比后面需求变了再迁移要省事得多。我一开始用内置通知等要加测试报告附件的时候还得回头重新配置一遍纯属重复劳动。2. 配置前必须做好的几项准备2.1 搞清 SMTP 服务器、端口和授权码的关系邮件要从 Jenkins 发出去本质上就是 Jenkins 作为邮件客户端通过 SMTP 协议把信交给邮件服务器再由邮件服务器投递给目标邮箱。所以配置的第一步是拿到发件邮箱的 SMTP 信息。这里有个容易被绕晕的点发件邮箱不是收件邮箱。你需要先准备一个专门用来发通知的邮箱账号然后用它自己的 SMTP 服务。我见过有人拿自己的私人邮箱当发件人结果授权码配错、被服务商限制、甚至把私人邮箱发爆完全不值得。正规做法是申请一个专用的通知邮箱比如通知机器人这种定位所有构建邮件都从它发出。SMTP 信息通常包含三样东西服务器地址、端口、安全方式。不同邮箱服务商的地址格式不一样一般形如邮件的服务商域名前缀加 smtp比如 smtp.某服务商.com 这种。端口常见的是 465 和 587465 对应 SSL 隐式加密587 对应 STARTTLS 显式加密还有老旧的 25 端口现在基本被各大服务商封掉不建议用。配的时候到底选哪个以你邮箱服务商官方文档里的推荐为准我自己的经验是优先 465配置简单、失败率低。还有一个关键点就是授权码。现在主流邮箱服务商都不再支持直接用登录密码做 SMTP 认证而是要求在网页端开启SMTP 服务并生成一个独立的授权码授权码和登录密码是两码事。很多新手第一次配置失败九成是因为拿登录密码去填了密码字段。这个东西有效期也需要注意有些服务商授权码长期有效有些会定期过期过期之后 Jenkins 那边就会开始报认证失败后面排查部分会再展开讲。2.2 系统管理里的两处邮件配置是新手最容易漏的Jenkins 里的邮件配置入口多这是很多人踩坑的根源。在 Manage Jenkins系统管理页面的 System系统配置里向下滚动能看到两个长得挺像的区域一个是E-mail Notification邮件通知对应内置邮件发送另一个是Extended E-mail Notification扩展邮件通知对应 Email Extension 插件。两个区域的字段几乎一样都是填 SMTP 服务器、默认后缀、用户名、密码。问题是你填了一个不代表另一个生效。如果你在任务的构建后操作里添加的是 Email-ext 的可编辑邮件通知那它走的是 Extended E-mail Notification 的配置如果你用内置的邮件通知走的是 E-mail Notification 的配置。两者内容不互通各填各的。我建议的做法是两处都老老实实填一遍相同的 SMTP 信息。虽然多费两分钟但能避免唉我明明配了啊这种排查半天的尴尬。另外Jenkins 在 Extended E-mail Notification 下面会有一个通过发送测试邮件测试配置的按钮可以填一个测试收件地址点一下验证 SMTP 是否连通。这个测试按钮能帮你确认基础链路通不通但它只是发一封固定内容邮件不等同于任务里的自定义模板和触发规则都能正常跑后面还得在任务里再验证一次。3. 实操配置让一次构建自动发出一封结果邮件3.1 安装 Email Extension 插件并确认系统设置第一步在 Manage Jenkins 的 Plugins插件管理页面里搜索 Email Extension安装后重启 Jenkins。插件名完整一点是 Email Extension Plugin安装完之后系统配置区域才会出现 Extended E-mail Notification。然后回到系统配置把两处 SMTP 都填好。我给一个参考配置注意用你自己环境的值替换配置项推荐值说明SMTP server你的邮箱服务商SMTP地址不要填网页登录地址Default user e-mail suffix你的域名用于给不带后缀的用户名自动补全邮箱Use SSL勾选对应 465 端口SMTP Port465 或 587取决于你的邮箱服务商推荐Reply-to Address通知邮箱地址方便收件人直接回复到通知邮箱CharsetUTF-8避免中文邮件乱码认证Credentials添加全局凭据用户名授权码别直接在Password字段填明文密码这里特别强调一下凭据的问题。老版本 Jenkins 是直接在配置页里填用户名/密码两个字段的新版本推荐在凭据里创建一条Username with password类型的全局凭据然后在 SMTP 认证里选择这条凭据。好处是凭据被加密存储配置页也支持不同环境复用团队里其他人操作时不用看到密码。我见过直接写在配置里的Jenkins 页面本身有权限控制还好但一旦配置页截图流出就非常被动所以能走凭据就走凭据。填完之后在 Extended E-mail Notification 页面底部先用发送测试邮件按钮验证一遍。如果报错检查服务器地址、端口、授权码三个字段挨个排除。测试邮件能收到说明基础链路已经通了。3.2 在流水线任务里接入邮件发送逻辑邮件配置好之后剩下的就是让构建任务在合适的时机触发邮件。有两种接入方式一种是在自由风格任务的构建后操作里可视化配置另一种是在流水线脚本里用emailext步骤调用。我个人更推荐流水线方式它把逻辑写在代码里模板、收件人、条件都跟任务定义一起版本化后面改起来清楚。用声明式流水线一个最小可用的发送逻辑长这样pipeline { agent any stages { stage(构建) { steps { echo 开始构建... // 这里替换成你真实的构建命令 sh ./build.sh } } } post { always { emailext( to: devexample.com, subject: 构建结果${env.JOB_NAME} #${env.BUILD_NUMBER} - ${currentBuild.currentResult}, body: p项目${env.JOB_NAME}/p p构建编号#${env.BUILD_NUMBER}/p p构建结果${currentBuild.currentResult}/p p构建地址a href${env.BUILD_URL}${env.BUILD_URL}/a/p p变更说明${env.CHANGE_LOG}/p ) } } }这段代码的意思很简单post { always { ... } }表示不管构建是成功、失败还是不稳定都会执行里面的步骤emailext是 Email Extension 插件提供的步骤to指定收件人subject是主题body是邮件正文。里面的${env.JOB_NAME}、${env.BUILD_NUMBER}这类是 Jenkins 的环境变量构建时会被替换成实际值currentBuild.currentResult是当前构建的结果状态。实际用下来我有几个注意点想说。第一收件人不要用recipientProviders那种花哨的动态分发先把to写死确认能收到后再按需调整第二post里的always会在每次构建都发邮件如果项目构建频率高邮件会很吵后面第 3.3 节专门讲触发规则的调整第三正文里最好带上构建地址的链接很多人收到邮件第一反应是点进去看控制台输出没有链接等于让收件人自己去 Jenkins 里找项目。如果你的任务用的是图形化界面不写脚本那就在构建后操作里添加可编辑邮件通知然后在配置界面设置收件人、主题、正文模板效果是一样的只是没有代码版本化那么方便。3.3 触发器怎么设置才不会被邮件轰炸邮件通知最让人反感的场景就是构建很频繁邮件跟机关枪一样扫射几天之后所有人设置了收件规则你的通知就等于白搞了。所以触发规则才是这套配置里真正需要认真思考的部分。Email Extension 插件支持很多触发条件最常用的有如下几个触发条件触发时机适合场景Always每次构建结束无论结果如何低频率、高关注度的构建比如发布包构建Failure仅构建失败时常规开发构建避免平时太多干扰Success仅构建成功时配合 Always 做失败、恢复双通知Unstable仅构建不稳定时测试有失败但未中断测试任务用于收集测试失败信息Change Failure上次成功、这次失败时才发减少连续失败时反复发信的噪音我自己的默认组合是Failure必发Unstable必发Success只在任务从失败转为成功时发一次——这个效果用Change Failure配对再配一个Change Success如果插件版本支持也能实现。核心思路是失败要知道恢复也要知道但别每次成功都刷一遍存在感。触发规则和post块怎么配合在声明式流水线里你可以按状态分别写post { failure { emailext( to: devexample.com, subject: 构建失败${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 见 Jenkins 构建页${env.BUILD_URL} ) } unstable { emailext( to: devexample.com, subject: 构建不稳定${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 测试有失败项见${env.BUILD_URL} ) } success { emailext( to: devexample.com, subject: 构建已恢复${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 上一次失败的构建已恢复见${env.BUILD_URL} ) } }这么写的好处是逻辑清楚失败、不稳定、恢复成功各走一支主题行一眼就能看出状态不需要在邮件正文里猜。我在实践中发现主题行把状态写到最前面非常有效尤其是手机端收邮件的时候通知栏里直接能看到构建失败四个字比点进去看正文强多了。4. 邮件内容高级定制把构建信息一次性讲清楚4.1 不要只发一行字用变量和模板把信息补全很多团队的 Jenkins 邮件开头是构建完成没了。这种邮件提供的信息量接近零收件人还得登录 Jenkins 去查。我们配置邮件目标应该是让收件人在收件箱里就完成 70% 的信息判断构建结果是什么、哪个项目、第几次构建、代码变更有哪些、测试结果如何、去哪里看详情。Email Extension 支持在主题和正文里使用变量。除了前面用到的$BUILD_NUMBER、$JOB_NAME、$BUILD_URL常用的还有这些变量含义$BUILD_STATUS构建结果状态SUCCESS/FAILURE/UNSTABLE/ABORTED$PROJECT_NAME任务名称$BUILD_URL本次构建的绝对地址$CAUSE触发本次构建的原因时间触发、手动触发、代码变更触发$CHANGELOG本次构建涉及的代码变更记录$TEST_COUNTS测试统计信息若测试任务有输出$BUILD_LOG_EXCERPT构建日志的摘要片段比如主题行可以写成这样[$BUILD_STATUS] $PROJECT_NAME 构建 #$BUILD_NUMBER - 变更:$CHANGELOG正文用一个简单的 HTML 模板把上面几个变量组织成清单收件人扫一眼就知道情况。Email Extension 也支持引用一个.jelly模板文件走Default Content区域直接编写 HTML 就行。我一般会加几行简单的 CSS 样式把失败状态标红、成功标绿判断依据还是$BUILD_STATUS变量模板会自动替换。这里提个醒HTML 模板里尽量别用过于复杂的 CSS有些邮件客户端会把样式剥掉越朴素兼容性越好。4.2 把测试报告和构建日志做成附件信息密度再翻一倍邮件正文写清楚了状态但很多场景下收件人还需要看细节。比如测试任务失败了你得知道是哪个用例挂的构建任务失败了你得知道是哪一步报错。这些信息靠人工去 Jenkins 页面里翻很费劲高效率的做法是让邮件带上附件。Email Extension 的attachLog参数可以控制是否把完整构建日志作为附件attachments参数可以指定附件路径。看一个带测试报告的例子post { failure { emailext( to: devexample.com, subject: 构建失败${env.JOB_NAME} #${env.BUILD_NUMBER}, body: 详见附件和 Jenkins 地址${env.BUILD_URL}, attachLog: true, attachments: target/surefire-reports/*.txt ) } }attachLog: true会把整个控制台日志打包进去省得收件人去页面上翻日志面板。attachments是相对于 workspace 的路径支持通配符比如target/surefire-reports/*.txt就能把测试报告全部附上。如果你用的是 HTML 报告注意有些邮箱客户端会阻止 HTML 附件改成压缩包.zip更稳妥。附件不是越多越好。我踩过一个大坑某个项目构建日志动辄几十兆测试报告也很占空间结果邮件发不出去或者发到对方邮箱直接被系统退回。很多邮件服务商对单封邮件附件大小有限制一般在 10MB 到 25MB 之间。所以现在我的做法是默认不附全量日志只在构建失败时附日志摘要测试报告如果太大先归档成压缩包再附。日志本身也可以考虑在流水线里用tee只保留末尾几十行作为摘要文件再把这个摘要文件附上。4.3 用主题前置判断给邮件分档成功、失败、不稳定各自一套文案邮件内容其实也是可以分状态的。与其一封邮件里既要提成功又要提失败不如通过 Groovy 脚本判断当前结果动态拼出不同的主题和正文。这里的思路是把邮件当成一个状态卡片来做成功卡片告诉你可以安心失败卡片告诉你看哪里不稳定卡片告诉你测试有杂音但不影响发布决策。实现方式也不复杂在emailext步骤之前先算好变量。比如script { if (currentBuild.currentResult SUCCESS) { emailSubject [成功] ${env.JOB_NAME} #${env.BUILD_NUMBER} emailBody 构建已通过产物可下载${env.BUILD_URL} emailTo devexample.com } else if (currentBuild.currentResult UNSTABLE) { emailSubject [不稳定] ${env.JOB_NAME} #${env.BUILD_NUMBER} emailBody 存在测试失败用例请尽快处理。详情${env.BUILD_URL} emailTo devexample.com } else { emailSubject [失败] ${env.JOB_NAME} #${env.BUILD_NUMBER} emailBody 构建失败存在阻断问题请立即跟进。日志${env.BUILD_URL} emailTo devexample.com } emailext(to: emailTo, subject: emailSubject, body: emailBody) }这种方式适合收件人组比较固定的场景。如果你的收件人还要按状态区分比如失败时除了开发还要抄送测试、成功时不抄送那就在每个分支里单独设置emailTo。把发送动作也拆到各分支里去写逻辑会更直观一些。一套稳定跑了一年多的项目我现在基本就这么处理成功邮件发给提测群和产物负责人失败邮件额外抄送项目经理附件只在失败时带。这套规则稳定之后团队里几乎没人会漏看构建问题邮件里该有的信息都在任何人接手都能快速定位。5. 发不出去、收不到、进垃圾箱常见问题与排查技巧实录5.1 一张表解决 80% 的邮件问题邮件配置里踩过的坑归纳起来就那么几类。下面这个速查表基本覆盖了绝大部分场景。现象常见原因排查方法系统设置测试邮件失败SMTP地址/端口/认证信息错误检查服务器地址、端口、授权码三步逐个替换再重发测试邮件成功但任务不发任务没配置发信逻辑或配置在错误的区域确认任务配置走的内置邮件还是扩展邮件与系统配置对应构建日志显示发送成功但收不到被收件方反垃圾策略拦截检查垃圾箱、白名单加发件地址、调整发件频率收到邮件但中文乱码字符集未设置或模板编码不对系统配置和邮件模板里都设置为 UTF-8邮件没带附件路径写错或通配符没匹配到文件到 workspace 下确认文件实际存在路径先写死文件名测试发件人被退回授权码过期或发件频繁被限流重新生成授权码降低通知频率收件人收到多个重复邮件同时配置了多个触发器和构建后操作检查任务里是否有重复的邮件步骤保留一个发送逻辑这张表背后有一个通用排查思路先区分是发送没执行还是发出去了没收到。前者去 Jenkins 控制台日志里看邮件步骤的执行记录后者去检查收件方邮箱的反垃圾规则。很多新手在收到未送达退信时第一反应是改代码里的邮件内容其实退信内容里通常会写明失败原因比如邮箱地址不存在、附件过大、发件人被拒先读退信能省很多时间。5.2 几个容易忽略的坑第一个坑是时区和时间显示。Jenkins 服务器默认时区不一定是你的本地时区邮件里如果直接打印构建时间戳收件人看到的可能是 UTC 时间比北京时间早 8 小时。解决方法是给 Jenkins 服务设置正确的时区或者在邮件模板里先用new Date().format(...)这类 Groovy 代码格式化时区后再输出。我自己一开始没注意测试报告跑完凌晨两点邮件显示前一天下午六点排查问题时对时间对不上号非常误导。第二个坑是凭据过期。很多服务商生成的 SMTP 授权码不是永久有效的过期后 Jenkins 发送邮件会报 535 认证失败之类错误。这个故障特点是前两天还能发今天突然不行了。我遇到过一次当时差点以为是邮箱服务商故障后来登录邮箱后台一看授权码过期提示重新生成一个新授权码更新到凭据里就好了。建议在日历里给授权码到期时间做个提醒免得到时候抓瞎。第三个坑是发送频率限制。通知邮箱如果短时间内发了太多邮件比如一个异常循环导致构建任务反复触发邮件服务商会临时封禁发件账号表现为发送报错或者发出去全部进垃圾箱。这类问题要根治源头检查触发器是不是设置了每两分钟就跑且每次必发把触发频率降下来同时给emailext步骤外层加一个状态判断确保只有任务状态变化时才发从源头减少邮件数量。第四个坑是自建邮箱服务器的情况。如果你的团队用自建邮件系统除了要配好 SMTP 之外还要确认 Jenkins 服务器的 IP 有没有被收件方邮箱列入黑名单以及域名有没有配好 SPF/DKIM 记录。这类问题在公共邮箱之间不太常见但在企业邮箱互发时经常出现表现为我们内部互相发没问题但外部邮箱收不到。处理方式一般就两条自建服务器的做好反垃圾认证记录或者直接用公共邮箱服务代发。5.3 用控制台日志和调试模式定位邮件连接问题当邮件完全没发出去第一现场不是邮箱后台而是 Jenkins 任务的控制台输出。构建执行到emailext步骤时它会打印相关日志比如发送邮件给 xxxexample.com、邮件发送成功/失败之类。有时候报错信息里会直接给出 SMTP 的错误码比如 535 表示认证失败、550 表示收件地址被拒、552 表示附件过大这些错误码配合速查表就能快速定位。如果日志信息不够还可以把邮件相关日志级别调到最详细。Jenkins 的系统配置里Extended E-mail Notification 区域有一个启用调试模式的选项勾上后会在构建日志里输出完整的 SMTP 会话记录能看到客户端发送的每一行命令和服务器返回的结果。这个模式对排查握手成功但认证失败连接被关闭这类底层问题很有用。我一般不出问题不开因为信息量太大正常任务日志会被淹没。另外一个笨但有效的方法是 telnet 到 SMTP 端口手动测连通性telnet smtp.example.com 465如果端口能通说明网络链路没问题如果超时或被拒绝就要检查服务器防火墙、安全组规则或者是不是端口选错了。这条对自建 Jenkins 服务器尤其重要因为很多公司内网服务器对外网 465/587 端口访问是受限的得先让网络管理员放通。6. 最后再说一点我个人折腾下来的心得构建邮件这套东西单看每个配置点都不复杂但它确实是把构建完成这件事从信息孤岛变成信息闭环的关键一步。我现在维护的流水线里邮件已经是标配但我会刻意控制邮件的数量和信息密度失败必发、恢复必发、不稳定分情况发、成功极高价值时才发邮件内容里永远有结果、编号、链接、变更、日志/报告这五个要素一份模板反复用在所有任务上。有几个小建议你可以直接用第一第一次配置时先用一次性测试任务验证整条链路别直接在正式的发布流水线上试不然手抖配错了几十封邮件直接轰炸所有人第二收件人地址里的默认后缀补全功能区分一下用户名和完整邮箱很多人填错只差一个 后缀导致半天收不到第三给通知邮箱单独建一个联系人分组比如构建通知组新人入职直接加组比邮件里每次写一堆收件人省事得多。如果你现在跑的项目还没有邮件通知我建议别只在系统配置里点个测试邮件就完事还是老老实实按这篇的思路把触发规则、模板、附件设计好一次性配到位。这套活儿熟练之后半小时内就能搞完但它省下来的等人发现构建挂了的时间远远超出你这半小时的付出。后面如果要用到更复杂的场景比如多分支流水线按分支路由邮件、对接定时报告、按团队自定义模板也都是在这个基础上扩展基础打好了就都不难。
