构建跑完了结果没人看这事儿听着不大但在实际团队里拖慢进度的往往就是这种小环节。我接手过不少Jenkins实例最典型的场景就是Job里塞了一大堆构建步骤通知却完全靠人肉刷新页面或者邮件功能配了半天构建失败了愣是一封邮件都不来。这篇文章准备跟你完整过一遍“Jenkins构建完自动发邮件”的方案从系统配置、插件选型到Job触发条件、HTML邮件模板再到最让人头疼的“为什么没收到邮件”排查思路一次性讲透。这套配置适合谁刚接触CI/CD的初级工程师、被构建失败邮件折磨的开发者、以及想给团队搭建规范通知流程的运维同学。读完之后你应该能自己搭出一套“构建成功/失败自动通知到相关人员”的邮件体系。1. 先弄明白这条通知链路里一共有几个节点想配好邮件通知不能上来就填服务器地址。先搞清楚一条“构建-邮件”的消息到底经过哪些环节后面排查问题才有的放矢。1.1 一个最简单的“构建跑完-邮件送达”故事假设你提交了代码触发了Jenkins构建两分钟后构建失败。这时候消息是这样流转的源码变更触发构建任务执行构建结束后Jenkins根据预设的“触发条件”判断当前结果如果符合条件通知插件会调用你配置的SMTP服务器SMTP服务器完成账号认证把邮件投递到收件人邮箱收件人看到邮件并作出反应。这个链路里只要有一个环节掉链子结果就是“构建失败了但没人知道”。而我见过最多的翻车点不是最后一步邮箱收不到而是第二步和第三步之间——要么触发条件没选对要么SMTP认证参数有问题。所以下文会花大量篇幅在这两个环节。1.2 为什么我不推荐用Jenkins自带的“邮件通知”Jenkins系统设置里确实有个自带的“邮件通知”模块新手机器上就能看到。它能用但仅限于“能发”这个层面。实际用起来有几个明显的硬伤收件人配置很单一很难做到“按角色分组发送”邮件内容写死成一句话无法动态插入构建号、变更列表、提交者触发逻辑只有“每次构建都发”和“失败才发”这类最基础的选项想加个自定义模板、按结果区分标题基本要靠插件才能实现。所以我一般直接建议用Email Extension插件也就是Jenkins里常说的“可编辑邮件通知”。它和内置功能的区别简单总结成一张表能力维度内置邮件通知Email Extension插件自定义HTML模板不支持支持还能多模板切换按构建结果设置触发规则基础丰富含“仍然失败”“恢复成功”等收件人分组/默认收件人机制简单灵活支持全局默认项目覆盖动态内容构建号/变更/日志弱强变量丰富维护成本低但鸡肋略高但值得选型逻辑很简单如果你想省事内置模块够用如果你想今后不返工直接上插件。本文后面的所有配置都以Email Extension为准。2. 系统级配置能让邮件“发出去”的三个关键位置很多人在这一步翻车。你以为填了个SMTP地址就行但实际需要同时关注三个关键点SMTP服务器参数、发件人信息、以及新版本Jenkins带来的认证编码问题。2.1 Extended E-mail Notification里的SMTP参数到底怎么填进入“系统管理-系统配置”往下找到“Extended E-mail Notification”区域。这里要填的核心参数如下SMTP服务器填你的邮箱服务商提供的SMTP地址。比如你自己团队的企业邮箱域名是md1.example.com那SMTP地址通常是smtp.md1.example.com端口默认25但很多云服务器和运营商封了25端口所以实际我推荐使用465或587勾选SSL/TLS对应端口选择465一般是SSL587一般是STARTTLS用户名发件邮箱账号密码这里有个容易忽略的点后面单独说。填完之后点击页面底部的“Test configuration by sending test e-mail”Jenkins会发一封测试邮件到“Test e-mail recipient”里填的地址。先跑通这一步再往下走。2.2 密码不等于邮箱登录密码授权码才是正解这里必须标记为重点。用个人邮箱或者部分企业邮箱做发件账号时SMTP认证要求用的往往不是邮箱的登录密码而是“授权码”或“SMTP专用密码”。我最初配置的时候直接把邮箱登录密码填进去测试一直报“Login denied”。后来查了下原来是该邮箱服务商在账号开启了双重验证之后外部SMTP认证必须使用单独生成的授权码而不是登录密码本身。所以遇到认证失败第一个要想到的不是换服务器而是确认自己填的是不是授权码。一般邮箱服务商都会在“设置-账户-安全”这种位置提供生成授权码的入口。2.3 一个容易被忽略的坑新版Jenkins的认证编码变化再讲一个我近期实际踩到的细节。从Jenkins某版本开始HTTP Basic Auth默认使用UTF-8而非原先的ISO-8859-1对用户名密码做Base64编码。这本来是更符合现代标准的改动但问题在于部分老式的SMTP服务器或邮件网关依然按照旧编码解析两者不匹配结果就是账号密码明明正确却一直报“Login denied”。如果你们公司正好用的是老邮件系统并且Jenkins版本较新认证失败时除了检查授权码之外还要考虑编码兼容问题。这种问题通常没有统一解法主流做法是要么升级邮件网关到支持UTF-8 Basic Auth的版本要么在Jenkins启动参数或代理层做兼容处理要么干脆换用支持OAuth2或API Key认证的邮件服务。我建议先在测试环境把这条链路跑通再上生产否则这类底层兼容问题会浪费很多时间。2.4 发件人地址与“Default Recipients”的关系系统配置里还有一个容易混淆的字段叫“Default Recipients”。它的含义是当Job没有单独指定收件人时默认把邮件发给谁。还有一个字段是“Default Subject”和“Default Content”这是全局模板Job如果没有覆盖就会用这套。注意这里填的收件人更多是“兜底”角色。真正到Job里通常你会覆盖它。怎么覆盖第3部分会说。3. Job配置把邮件和构建结果正确绑定系统配置只解决“能发”。接下来的问题是“什么时候发”“发给谁”“以什么形式发”。这些都在Job层面完成。3.1 自由风格项目里最常用的挂法构建后操作如果你用的是经典的“自由风格项目”配置邮件通知的位置在“构建后操作”里添加“可编辑邮件通知”。进去之后需要关心几组设置触发条件也就是“什么结果才发邮件”。常用选项包括Always无论成功失败都发Success成功才发Failure失败才发Unstable构建不稳定才发Still Failing上次失败这次仍然失败时才发避免重复轰炸。收件人这里填实际接收人。多个收件人用逗号分隔可以填邮箱地址也可以填变量占位符比如“$DEFAULT_RECIPIENTS”表示继承全局默认收件人。邮件主题和内容支持变量比如“$PROJECT_NAME - Build # $BUILD_NUMBER - $STATUS”。我个人的习惯是触发条件不选Always而是组合使用Failure Still Failing保证失败时第一时间通知之后仍然失败时再发一次提醒还在挂Success成功后发一次让团队知道修复完成Unstable一般单独发。这样的好处是邮件不会变成“每跑一次就轰炸一次”的噪音。3.2 用Pipeline脚本精确控制通知时机如果项目用的是Pipeline流水线配置方式就不是图形界面了而是直接在Jenkinsfile里调emailext步骤。一个很典型的写法是这样的pipeline { agent any stages { stage(Build) { steps { echo building... } } } post { success { emailext( subject: 构建成功${env.JOB_NAME} - ${env.BUILD_NUMBER}, body: 项目 ${env.JOB_NAME} 构建成功详情${env.BUILD_URL}, to: dev-teamexample.com ) } failure { emailext( subject: 构建失败${env.JOB_NAME} - ${env.BUILD_NUMBER}, body: 项目 ${env.JOB_NAME} 构建失败请尽快处理。详情${env.BUILD_URL}, to: dev-teamexample.com ) } } }用Pipeline的好处是逻辑更透明而且可以跟构建过程中的自定义条件结合比如“只有某个阶段失败才通知”这是图形界面比较难做到的事情。3.3 高频迷惑点为什么我填了收件人邮件还是发给了默认地址这个问题在社区里被问烂了但确实高度容易踩中。在“可编辑邮件通知”的配置界面里如果你填了“收件人”但下面的“高级设置”里没有勾选“Replace Default Recipients”那最终生效的收件人列表会是“全局默认收件人你填的收件人”合并后的结果。换句话说你以为只发给团队三个人结果全局配置里的那位兜底收件人也会收到。更麻烦的是如果全局默认收件人填了一个已经离职的同事邮箱那邮件依然会往那个老地址发。所以我每次配置新Job时都会刻意检查这个复选框。别小看它很多“说好只发给A结果B也收到了”的诡异情况根因就在这里。4. 邮件内容从“能收到”进化到“值得看”邮件能发出去只是第一步。如果一封构建通知长这样“Build failed”那看了等于没看还是得点进Jenkins页面查。既然都花精力做通知了不如把邮件做成一个可以直接读取的构建报告。4.1 模板变量是邮件内容的灵魂可编辑邮件通知支持在主题和正文中使用大量预置变量。下面这组最常用建议直接收藏变量含义$PROJECT_NAME项目名称$BUILD_NUMBER构建号$BUILD_STATUS构建状态$BUILD_URL构建详情页链接$CAUSE触发原因$CHANGES变更列表可带格式$CHANGESET变更集详情$DEFAULT_RECIPIENTS全局默认收件人$BUILD_LOG构建日志全文$BUILD_LOG_EXCERPT构建日志片段主题里我最常用的格式是[CI][$PROJECT_NAME] Build #$BUILD_NUMBER $BUILD_STATUS后缀的$BUILD_STATUS会自动变成SUCCESS、FAILURE、UNSTABLE等关键词。用统一的主题前缀团队在邮箱里搜索时特别方便。4.2 做出一个简洁的构建报告模板正文我建议用HTML因为可以排版。一个尽量精简但信息完整的模板如下html body h2${PROJECT_NAME} - Build # ${BUILD_NUMBER}/h2 pstrong状态/strong${BUILD_STATUS}/p pstrong触发原因/strong${CAUSE}/p pstrong构建地址/stronga href${BUILD_URL}${BUILD_URL}/a/p hr/ h3变更内容/h3 p${CHANGES}/p hr/ h3构建日志片段/h3 pre${BUILD_LOG_EXCERPT}/pre /body /html这里说三个实际经验第一“${CHANGES}”默认输出可能很丑建议在模板里保留一个简单区域让收件人一眼看到这次构建涉及了哪些提交第二日志片段不要用全文尤其大型项目构建日志可能有几百KB邮件服务商对附件或者正文体量都有限制。建议用“BUILD_LOG_EXCERPT”这种截断版本或者自己写Groovy脚本提取关键行第三中文字符乱码问题。HTML模板要在头部明确指定字符集meta charsetUTF-8同时在可编辑邮件通知的高级设置里把“Content Type”选成“HTML(text/html)”。否则中文内容发出去经常变成乱码白忙活一场。4.3 想抓取构建日志的特定行怎么办默认模板里的$BUILD_LOG_EXCERPT可以截取日志片段但如果你想更精准地提取“错误信息后的20行”可以用Pipeline脚本预处理日志。基本思路是在构建阶段把Console日志输出到文件用shell工具做提取然后保存成自定义变量传给emailext模板。def getFailureLog() { sh grep -A 20 BUILD FAILURE console.log failure_snippet.txt || true return readFile(failure_snippet.txt).trim() }需要注意console.log这个文件在Pipeline里不一定默认存在通常需要把日志输出重定向到工作区文件比如用“sh xxx build.log 21”再配合readFile读取。我自己更推荐另一种方式由构建工具直接生成错误摘要比如在Maven构建后解析测试报告再把失败用例列表注入邮件。这样邮件里的信息比原始日志更有价值。5. 构建失败却没有邮件一套可复现的排查思路邮件没到是Jenkins领域里最常见也最恼人的问题。我总结了一套排查思路按顺序走基本能在10分钟内定位问题。5.1 先分清是“没发出来”还是“没收到”很多人在这一步浪费了大量时间。直接打开Jenkins的构建记录点击对应构建编号在左侧找到“Console Output”控制台输出搜索“Email”关键字。如果看到类似“Email was triggered for: Failure”的日志说明Jenkins已经判断触发条件成立并尝试发送。此时如果附近有“Sending email to: xxxexample.com”的记录说明邮件进入了发送流程。如果连“Email was triggered”都没有那问题大概率出在触发条件或插件Job配置上跟邮箱服务器无关。5.2 沿着三条路径逐段验证当确认Jenkins已经尝试发送后再分三路排查路径一Jenkins日志里的SMTP错误控制台输出里通常会有“Failed to send out e-mail”之类的信息后面跟具体的异常描述。常见的是“Login denied”认证失败检查授权码或者编码问题“Could not connect to SMTP host”网络不通或端口被封“Timeout”服务器响应慢或端口选错。路径二发件邮箱的“已发送”或“递送失败回执”部分企业邮箱可以在网页端查看“已发送”记录。如果邮件显示发送成功问题在收件端如果显示退信看退信原因。路径三收件端的垃圾箱与拒收策略邮件发是发出去了但可能被对方邮件网关拦截。尤其是正文包含大量构建日志、链接指向内网地址时容易被当成可疑邮件。碰到这种情况让收件人先查垃圾箱并把发件地址加入白名单。5.3 常见问题对照表现象可能原因处理方式测试邮件报Login denied密码填的是登录密码而非授权码改用SMTP授权码测试邮件报Login denied且授权码正确新版Jenkins的Base64编码与老邮件系统不兼容升级网关或做代理兼容提交代码后构建失败但没收到邮件触发条件未包含Failure检查“可编辑邮件通知”的触发勾选收到的邮件的收件人包含了不在预期的人未勾选Replace Default Recipients勾选该选项并检查全局默认收件人收到邮件但中文乱码Content Type未设置或模板缺字符集声明检查模板meta标签和高级设置邮件服务商退信称附件过大模板中内嵌了完整构建日志改用日志片段或外链日志6. 进阶让通知机制真正内化到团队流程配置做完不算结束。我在实际项目里还会再做一轮“验证规范化”这部分建议你也做一遍。6.1 用一次“故意失败”做全链路烟雾测试邮件通知和普通功能不一样不做失败验证你永远不知道配置是否可靠。我说的不是点一下“立即构建”而是在一个测试分支上故意制造一次构建失败然后观察失败邮件是否在规定时间发出收件人是否在预期名单里邮件HTML渲染是否正常日志截取是否有空值。我一般会在Pipeline里加一个临时阶段stage(Smoke Failure Test) { steps { sh exit 1 } }等验证完邮件通知正常再把这个阶段删掉。这个过程看起来简单但能一次性校验掉插件配置、SMTP认证、模板解析、收件人替换等全部环节。6.2 团队协作中的邮件规范建议邮件通知如果做得不好就是全员轰炸机。我的建议是建立统一的邮件主题前缀比如“[CI-Alert]”方便邮箱端设置过滤规则成功邮件和失败邮件用不同前缀比如“构建成功”和“构建失败”让人一眼识别紧急程度收件人按角色区分而不是一律发全组对于“仍然失败”的通知可以考虑降低发送频率只发给当前修复负责人。6.3 后续还能继续做的事邮件通知和即时通讯通知并不互斥。有些团队会在邮件基础上再接入企业微信或钉钉的机器人通知把“构建失败”直接推送到群聊。这个方向很有价值。实际上一旦你理解了触发条件和通知插件的配合逻辑接其他通道只是换一个适配器的问题。我个人还有一个习惯把“邮件通知是否触发”也纳入构建报告本身也就是在Pipeline输出里加上一行“notification: email sent”之类的信息。这不影响功能但极大方便后续排查。最后再分享一个小技巧邮件模板和主题字符串我建议统一放到Jenkins的全局配置里而不是散落在各个Job中。这样以后要改团队通知模板只需要改一处所有Job同步生效。免得十几个Job一个个点进去改改到一半自己都想放弃。希望这套配置和排错思路能帮你少熬几个夜。
