一、Jenkins 企业微信通知插件使用手册

1.1 插件简介

Qy-WeChat-Notification 是一个 Jenkins 插件，用于将构建结果通过企业微信机器人发送通知。该插件可以在构建完成后，将构建状态、构建信息等内容推送到企业微信群聊中，方便团队成员及时了解构建情况。

支持通过企业微信群机器人发送构建通知
支持在 Pipeline 脚本和自由风格项目中使用
可与其他插件（如 Build User Vars）结合使用，增强通知功能
支持@指定用户或所有人

TIP

对于需要自定义复杂通知内容的场景，可以使用Shell脚本直接调用企业微信Webhook API

企微群机器人使用说明

1.2 插件安装

官方地址： https://plugins.jenkins.io/qy-wechat-notification/
安装方式：系统管理 -> 管理插件 -> 可选插件 -> Qy-WeChat-Notification -> 直接安装

1.3 基础配置

1.3.1 获取企业微信群机器人 Webhook 地址

在企业微信群中，点击右上角的群设置图标
选择"群机器人"
点击"添加机器人"，选择"自定义"机器人
设置机器人名称和头像
复制生成的 Webhook 地址，格式类似：https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxxxxx

1.3.2 系统配置

进入 Jenkins 系统管理 -> 系统配置
找到 "企业微信通知配置" 部分
添加企业微信机器人配置：
- 构建环境名称
- 默认Webhook地址
- 默认通知UserID[可选]
- 默认通知手机号码[在不知道userid 的情况下可使用手机号]
点击 "保存" 按钮

1.4 使用方法

1.4.1 在 Pipeline 中使用插件

在 Pipeline 脚本中，可以使用 qyWechatNotification 步骤发送企业微信通知：

TIP

可使用Jenkins 的片段生成器生成插件的流水线语法

groovy

pipeline {
    agent any
    
    stages {
        stage('构建') {
            steps {
                echo "执行构建步骤..."
            }
        }
    }
    
    post {
        always {
            wrap([$class: 'BuildUser']) {
                script{
                    buildName "#${BUILD_NUMBER} - ${env.BUILD_USER_ID}"// 更改构建名称
                    qyWechatNotification mentionedId: '', mentionedMobile: 'ALL,13012345678', webhookUrl: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx'
                }
            }
        }
    }
}

1.4.2 使用自定义脚本发送模板卡片通知

上面的插件属实有点功能太简单了，对于需要自定义通知内容的场景，可以编写Shell脚本通过企业微信Webhook API发送更丰富的模板卡片通知：

groovy

pipeline {
    agent any
    
    environment {
        BUILD_TIME = sh(script: "echo `date '+%Y-%m-%d %H:%M:%S'`", returnStdout: true).trim()
    }
    
    stages {
        stage('构建') {
            steps {
                echo "执行构建步骤..."
            }
        }
    }
    
    post {
        always {
            wrap([$class: 'BuildUser']) {
                script {
                    // 设置构建名称
                    buildName "#${BUILD_NUMBER} - ${env.BUILD_USER_ID ?: '系统'}"
                    
                    // 构建状态相关信息
                    def buildUser = env.BUILD_USER ?: '系统自动'
                    def buildStatus = currentBuild.currentResult
                    def statusIcon = buildStatus == 'SUCCESS' ? '✅' : '❌'
                    
                    // 创建临时 JSON 文件
                    writeFile file: 'template_card.json', text: """
                    {
                        "msgtype": "template_card",
                        "template_card": {
                            "card_type": "text_notice",
                            "source": {
                                "icon_url": "https://jenkins.io/images/logos/jenkins/jenkins.png",
                                "desc": "Jenkins构建通知",
                                "desc_color": 0
                            },
                            "main_title": {
                                "title": "Jenkins构建完成通知",
                                "desc": "${env.JOB_NAME} - #${BUILD_NUMBER}"
                            },
                            "emphasis_content": {
                                "title": "${statusIcon} ${buildStatus}",
                                "desc": "构建状态"
                            },
                            "quote_area": {
                                "type": 1,
                                "url": "${env.BUILD_URL}",
                                "title": "构建日志摘要",
                                "quote_text": "构建分支: ${env.GIT_BRANCH ?: 'master'}\\n构建时间: ${BUILD_TIME}\\n构建用户: ${buildUser}"
                            },
                            "sub_title_text": "构建详细信息",
                            "horizontal_content_list": [
                                {
                                    "keyname": "构建分支",
                                    "value": "${env.GIT_BRANCH ?: 'master'}"
                                },
                                {
                                    "keyname": "构建编号",
                                    "value": "#${BUILD_NUMBER}"
                                },
                                {
                                    "keyname": "触发用户",
                                    "value": "${buildUser}"
                                },
                                {
                                    "keyname": "构建日志",
                                    "value": "点击查看",
                                    "type": 1,
                                    "url": "${env.BUILD_URL}console"
                                }
                            ],
                            "jump_list": [
                                {
                                    "type": 1,
                                    "url": "${env.BUILD_URL}",
                                    "title": "查看构建详情"
                                },
                                {
                                    "type": 1,
                                    "url": "${env.BUILD_URL}changes",
                                    "title": "查看变更记录"
                                }
                            ],
                            "card_action": {
                                "type": 1,
                                "url": "${env.BUILD_URL}"
                            }
                        }
                    }
                    """
                    
                    // 发送企业微信通知
                    sh """
                        #!/bin/sh
                        # 企业微信机器人 Webhook 地址
                        WEBHOOK_URL="https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxx"
                        
                        # 发送请求
                        curl -s -H "Content-Type: application/json" -X POST -d @template_card.json \$WEBHOOK_URL
                        
                        # 清理临时文件
                        rm template_card.json
                    """
                }
            }
        }
    }
}

1.4.3 使用自定义脚本发送Markdown通知

如果您更喜欢使用Markdown格式的通知，也可以使用以下示例：

groovy

pipeline {
    agent any
    
    environment {
        BUILD_TIME = sh(script: "echo `date '+%Y-%m-%d %H:%M:%S'`", returnStdout: true).trim()
    }
    
    stages {
        stage('构建') {
            steps {
                echo "执行构建步骤..."
            }
        }
    }
    
    post {
        success {
            wrap([$class: 'BuildUser']) {
                script {
                    // 设置构建名称
                    buildName "#${BUILD_NUMBER} - ${env.BUILD_USER_ID ?: '系统'}"
                    
                    // 调用自定义Shell脚本发送企业微信通知
                    sh """
                        #!/bin/sh
                        # 企业微信机器人key
                        CHAT_WEBHOOK_KEY="xxxxxxxxxxxx"
                        CHAT_CONTENT_TYPE='Content-Type: application/json'
                        CHAT_WEBHOOK_URL='https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key'
                        
                        # 构建相关信息
                        BUILD_USER="${env.BUILD_USER ?: '系统自动'}"
                        JOB_NAME="${env.JOB_NAME}"
                        URL_JOB="${env.BUILD_URL}"
                        URL_LOG="${env.BUILD_URL}console"
                        BUILD_TIME="${env.BUILD_TIME}"
                        GIT_BRANCH="${env.GIT_BRANCH ?: 'master'}"
                        JOB_TIPS1="13012345678" # 需要@的人的手机号
                        
                        echo "## 发送构建成功通知"
                        curl "\${CHAT_WEBHOOK_URL}=\${CHAT_WEBHOOK_KEY}" \\
                        -H "\${CHAT_CONTENT_TYPE}" \\
                        -d '
                           {
                                "msgtype": "markdown",
                                "markdown": {
                                 "content": "<font color=\\"warning\\">**Jenkins任务通知**</font> \\n
                                 >构建人：<font color=\\"comment\\">'"\${BUILD_USER}"'</font>
                                 >构建时间：<font color=\\"comment\\">'"\${BUILD_TIME}"'</font>
                                 >任务名称：<font color=\\"comment\\">'"\${JOB_NAME}"'</font>
                                 >构建分支：<font color=\\"comment\\">'"\${GIT_BRANCH}"'</font>
                                 >任务地址：<font color=\\"comment\\">[点击查看]('"\${URL_JOB}"')</font>
                                 >构建日志：<font color=\\"comment\\">[点击查看]('"\${URL_LOG}"')</font>
                                 >构建状态：<font color=\\"info\\">**Success**</font> \\n
                                 >任务已构建完成请确认：<@'"\${JOB_TIPS1}"'>"
                                }
                           }
                        '
                    """
                }
            }
        }
        
        failure {
            wrap([$class: 'BuildUser']) {
                script {
                    // 设置构建名称
                    buildName "#${BUILD_NUMBER} - ${env.BUILD_USER_ID ?: '系统'}"
                    
                    // 调用自定义Shell脚本发送企业微信通知
                    sh """
                        #!/bin/sh
                        # 企业微信机器人key
                        CHAT_WEBHOOK_KEY="xxxxxxxxxxxxxxxxxx"
                        CHAT_CONTENT_TYPE='Content-Type: application/json'
                        CHAT_WEBHOOK_URL='https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key'
                        
                        # 构建相关信息
                        BUILD_USER="${env.BUILD_USER ?: '系统自动'}"
                        JOB_NAME="${env.JOB_NAME}"
                        URL_JOB="${env.BUILD_URL}"
                        URL_LOG="${env.BUILD_URL}console"
                        BUILD_TIME="${env.BUILD_TIME}"
                        GIT_BRANCH="${env.GIT_BRANCH ?: 'master'}"
                        JOB_TIPS1="13012345678" # 需要@的人的手机号
                        
                        echo "## 发送构建失败通知"
                        curl "\${CHAT_WEBHOOK_URL}=\${CHAT_WEBHOOK_KEY}" \\
                        -H "\${CHAT_CONTENT_TYPE}" \\
                        -d '
                           {
                                "msgtype": "markdown",
                                "markdown": {
                                 "content": "<font color=\\"warning\\">**Jenkins任务通知**</font> \\n
                                 >构建人：<font color=\\"comment\\">'"\${BUILD_USER}"'</font>
                                 >构建时间：<font color=\\"comment\\">'"\${BUILD_TIME}"'</font>
                                 >任务名称：<font color=\\"comment\\">'"\${JOB_NAME}"'</font>
                                 >构建分支：<font color=\\"comment\\">'"\${GIT_BRANCH}"'</font>
                                 >任务地址：<font color=\\"comment\\">[点击查看]('"\${URL_JOB}"')</font>
                                 >构建日志：<font color=\\"comment\\">[点击查看]('"\${URL_LOG}"')</font>
                                 >构建状态：<font color=\\"comment\\">**Failure**</font>
                                 >任务已构建完成请确认：<@'"\${JOB_TIPS1}"'>"
                                }
                           }
                        '
                    """
                }
            }
        }
    }
}

1.6 将通知脚本封装为共享库

对于多个项目需要使用相同通知逻辑的情况，可以将通知脚本封装为 Jenkins 共享库，方便复用：

1.6.1 创建共享库文件

在 Jenkins 共享库中创建 vars/qyWechatNotify.groovy 文件：

groovy

#!/usr/bin/env groovy

/**
 * 发送企业微信通知
 * @param webhookKey 企业微信机器人的 webhook key
 * @param buildUser 构建用户
 * @param buildTime 构建时间
 * @param jobName 任务名称
 * @param buildUrl 构建链接
 * @param buildStatus 构建状态
 * @param mentionedMobile 需要@的手机号，多个用逗号分隔，使用 ALL 表示@所有人
 * @param extraInfo 额外信息，格式为 Map
 */
def call(String webhookKey, String buildUser, String buildTime, String jobName, 
         String buildUrl, String buildStatus, String mentionedMobile = '', Map extraInfo = [:]) {
    
    def statusColor = buildStatus == 'SUCCESS' ? 'info' : 'comment'
    def statusText = buildStatus == 'SUCCESS' ? 'Success' : 'Failure'
    
    // 构建额外信息内容
    def extraContent = ""
    extraInfo.each { key, value ->
        extraContent += ">$key：<font color=\"comment\">$value</font>\n"
    }
    
    // 构建 Shell 脚本
    def script = """
        #!/bin/sh
        CHAT_WEBHOOK_KEY="${webhookKey}"
        CHAT_CONTENT_TYPE='Content-Type: application/json'
        CHAT_WEBHOOK_URL='https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key'
        
        # 构建相关信息
        BUILD_USER="${buildUser}"
        JOB_NAME="${jobName}"
        URL_JOB="${buildUrl}"
        URL_LOG="${buildUrl}console"
        BUILD_TIME="${buildTime}"
        STATUS="${statusText}"
        STATUS_COLOR="${statusColor}"
        JOB_TIPS1="${mentionedMobile}" # 需要@的人的手机号
        
        echo "## 发送构建通知"
        curl "\${CHAT_WEBHOOK_URL}=\${CHAT_WEBHOOK_KEY}" \\
        -H "\${CHAT_CONTENT_TYPE}" \\
        -d '
           {
                "msgtype": "markdown",
                "markdown": {
                 "content": "<font color=\\"warning\\">**Jenkins任务通知**</font> \\n
                 >构建人：<font color=\\"comment\\">'"\${BUILD_USER}"'</font>
                 >构建时间：<font color=\\"comment\\">'"\${BUILD_TIME}"'</font>
                 >任务名称：<font color=\\"comment\\">'"\${JOB_NAME}"'</font>
                 ${extraContent}
                 >任务地址：<font color=\\"comment\\">[点击查看]('"\${URL_JOB}"')</font>
                 >构建日志：<font color=\\"comment\\">[点击查看]('"\${URL_LOG}"')</font>
                 >构建状态：<font color=\\"\${STATUS_COLOR}\\">**'"\${STATUS}"'**</font> \\n
                 >任务已构建完成请确认：<@'"\${JOB_TIPS1}"'>"
                }
           }
        '
    """
    
    // 执行脚本
    sh script
}

1.6.2 在 Pipeline 中使用共享库

groovy

@Library('jenkins-shared-library') _

pipeline {
    agent any
    
    environment {
        BUILD_TIME = sh(script: "echo `date '+%Y-%m-%d %H:%M:%S'`", returnStdout: true).trim()
        VERSION = sh(script: "echo `date '+%Y%m%d'`-${env.BUILD_ID}", returnStdout: true).trim()
    }
    
    parameters {
        gitParameter branch: '', branchFilter: '.*', defaultValue: 'main', description: '选择构建分支', 
                    name: 'GIT_BRANCH', quickFilterEnabled: true, selectedValue: 'NONE', sortMode: 'ASCENDING', 
                    tagFilter: '*', type: 'GitParameterDefinition'
        choice(name: 'ENV', choices: ['开发环境', '测试环境', '生产环境'], description: '部署环境')
    }
    
    stages {
        stage('检出代码') {
            steps {
                checkout scmGit(
                    branches: [[name: "${params.GIT_BRANCH}"]], 
                    extensions: [], 
                    userRemoteConfigs: [[
                        credentialsId: 'git-credentials', 
                        url: 'http://git.example.com/project/repo.git'
                    ]]
                )
            }
        }
        
        stage('构建') {
            steps {
                echo "执行构建步骤..."
            }
        }
    }
    
    post {
        always {
            wrap([$class: 'BuildUser']) {
                script {
                    // 设置构建名称和描述
                    buildName "#${BUILD_NUMBER}: ${params.GIT_BRANCH}"
                    buildDescription """
                    <b>分支:</b> ${params.GIT_BRANCH}<br>
                    <b>环境:</b> ${params.ENV}<br>
                    <b>版本:</b> ${VERSION}<br>
                    <b>构建者:</b> ${env.BUILD_USER ?: '系统自动'}<br>
                    <b>状态:</b> ${currentBuild.currentResult}<br>
                    """
                    
                    // 使用共享库发送企业微信通知
                    qyWechatNotify(
                        'c5ae4999-be22-491f-xxxxxxxxxxxxx',  // webhook key
                        env.BUILD_USER ?: '系统自动',         // 构建用户
                        env.BUILD_TIME,                      // 构建时间
                        env.JOB_NAME,                        // 任务名称
                        env.BUILD_URL,                       // 构建链接
                        currentBuild.currentResult,          // 构建状态
                        '13012345678',                       // @的手机号
                        [                                    // 额外信息
                            '构建分支': params.GIT_BRANCH,
                            '部署环境': params.ENV,
                            '构建版本': VERSION
                        ]
                    )
                }
            }
            
            // 清理工作区
            cleanWs()
        }
    }
}

1.7 注意事项

消息频率限制：企业微信机器人有消息发送频率限制，过于频繁的通知可能会被限制。
消息内容限制：
- Markdown 消息：最长不超过 4096 个字节
- 文本消息：最长不超过 2048 个字节
- 模板卡片：各字段有不同的长度限制，详见官方文档
@功能使用：
- 使用插件，在不知道用户 id 的情况下，可以通过 mentionedMobile 参数可以@指定手机号的用户； mentionedMobile: 'ALL' 可以@所有人
安全性考虑：
- 避免在通知中包含敏感信息，如密码、密钥等
- Webhook 地址应妥善保管，避免泄露
通知时机选择：
- 根据项目需求选择合适的通知时机，避免过多无用通知
- 可以根据构建结果选择性发送通知，如只在构建失败时通知
与其他通知方式结合：
- 可以与邮件通知等其他方式结合使用，确保重要信息能够及时传达
- 对于不同的通知目标，可以选择不同的通知方式

OpenEuler

操作系统优化&安全问题

Jenkins 常规配置&插件管理

Jenkins 优秀插件讲解

Jenkins Pipeline 必知必会

Gitlab代码库&Jenkins集成

构建工具与Jenkins集成实践

Jenkins&Sonarqube集成

一、Jenkins 企业微信通知插件使用手册

1.1 插件简介

1.2 插件安装

1.3 基础配置

1.3.1 获取企业微信群机器人 Webhook 地址

1.3.2 系统配置

1.4 使用方法

1.4.1 在 Pipeline 中使用插件

1.4.2 使用自定义脚本发送模板卡片通知

1.4.3 使用自定义脚本发送Markdown通知

1.6 将通知脚本封装为共享库

1.6.1 创建共享库文件

1.6.2 在 Pipeline 中使用共享库

1.7 注意事项

Jenkins 优秀插件讲解

一、Jenkins 企业微信通知插件使用手册 ​

1.1 插件简介 ​

1.2 插件安装 ​

1.3 基础配置 ​

1.3.1 获取企业微信群机器人 Webhook 地址 ​

1.3.2 系统配置 ​

1.4 使用方法 ​

1.4.1 在 Pipeline 中使用插件 ​

1.4.2 使用自定义脚本发送模板卡片通知 ​

1.4.3 使用自定义脚本发送Markdown通知 ​

1.6 将通知脚本封装为共享库 ​

1.6.1 创建共享库文件 ​

1.6.2 在 Pipeline 中使用共享库 ​

1.7 注意事项 ​

一、Jenkins 企业微信通知插件使用手册

1.1 插件简介

1.2 插件安装

1.3 基础配置

1.3.1 获取企业微信群机器人 Webhook 地址

1.3.2 系统配置

1.4 使用方法

1.4.1 在 Pipeline 中使用插件

1.4.2 使用自定义脚本发送模板卡片通知

1.4.3 使用自定义脚本发送Markdown通知

1.6 将通知脚本封装为共享库

1.6.1 创建共享库文件

1.6.2 在 Pipeline 中使用共享库

1.7 注意事项