Jenkins email-ext插件自定义Groovy邮件模板编写报错求助

Groovy模板解析报错绝大多数情况不是Groovy语法本身的问题，而是插件加载规则、上下文配置、模板编写规范不符合要求，尤其是涉及XML、PDF附件发送的场景，网上大量示例基于多年前的老版本插件，和新版Pipeline的兼容逻辑不一致，按以下步骤配置即可正常运行。

1. Pipeline侧emailext配置注意事项 #

• 模板文件不要内联写在body参数中，必须单独存储为.groovy文件，要么放在Jenkins主目录的$JENKINS_HOME/email-templates/路径下作为全局模板，要么放在代码仓库中随项目版本管理
• 引用模板时路径不要写错：全局模板直接填文件名即可，项目内模板需要拼接工作区路径
• 附件直接通过attachmentsPattern参数配置，支持通配符匹配XML、PDF文件，不需要在模板里单独处理附件逻辑

可直接复用的配置示例：

post {
    always {
        emailext (
            to: 'recipient@example.com',
            subject: "构建通知: ${env.JOB_NAME} [${currentBuild.currentResult}] - #${env.BUILD_NUMBER}",
            // 引用全局模板直接写文件名，项目内模板写法为 template="${WORKSPACE}/jenkins/templates/your-template.groovy"
            body: '${SCRIPT, template="custom-build-notify.groovy"}',
            // 匹配工作区下所有需要发送的PDF、XML附件
            attachmentsPattern: '**/*.pdf, **/*.xml',
            attachBuildLog: false,
            compressLog: false
        )
    }
}

注意：body参数的外层必须用单引号包裹，如果用双引号，Pipeline会提前解析字符串里的${}占位符，导致插件拿不到模板指令直接报错。

2. Groovy模板编写规范 #

模板运行在插件的独立Groovy沙箱中，和Pipeline脚本的运行上下文完全隔离，必须遵守以下规则：

• 所有输出到邮件正文的内容，必须通过out.println()方法输出，不要直接在脚本顶层写裸HTML内容
• 模板内置可直接使用的上下文变量包括build（当前构建实例对象）、env（构建环境变量）、out（输出流对象），不要在模板中调用Pipeline专属步骤（比如sh、echo、writeFile等），沙箱没有这些步骤的执行权限
• 不要给模板加类定义、main方法包裹，模板是脚本执行模式，直接写逻辑即可

最小可用模板示例（custom-build-notify.groovy）：

// 从上下文获取构建信息
def buildStatus = build.result ?: 'SUCCESS'
def jobName = build.project.fullName
def buildNum = build.number
def buildLink = env.BUILD_URL

// 输出邮件正文HTML
out.println """
<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"></head>
<body>
<h3>构建结果：${buildStatus}</h3>
<ul>
    <li>任务名称：${jobName}</li>
    <li>构建编号：#${buildNum}</li>
    <li>构建详情：<a href="${buildLink}">跳转至Jenkins查看</a></li>
</ul>
<p>本次构建的PDF测试报告、XML结果文件已作为附件发送，请查收。</p>
</body>
</html>
"""

3. 常见报错排查点 #

如果按以上配置仍然报解析错误，逐一排查以下问题：

• 语法校验：把模板内容复制到本地Groovy语法校验工具检查，最常见的错误是三引号字符串未闭合、括号不匹配、单引号字符串内错误使用${}变量插值
• 文件权限：如果使用全局模板，确认$JENKINS_HOME/email-templates/目录下的模板文件对Jenkins运行用户有可读权限，插件读不到文件时也会抛出解析异常
• 版本兼容：将email-ext插件升级到2.82及以上版本，低于该版本的Groovy沙箱存在已知兼容bug，会将合法脚本判定为解析错误
• 特殊字符：模板内容不要包含未转义的<%、%>等老式JSP模板标记，新版插件不支持该语法

内容的提问来源于stack exchange，提问作者Manu M