第三篇：《Jenkins Pipeline as Code：Declarative Pipeline 深度实战》

上一篇我们通过 Jenkins UI 运行了第一个 Pipeline。但真正的"Pipeline as Code"理念要求将流水线定义存放在代码仓库中，与应用程序代码一起进行版本管理。本文深入讲解 Jenkins 声明式 Pipeline（Declarative Pipeline）的核心语法，包括 agent、environment、parameters、triggers、when、post 等指令，并通过一个支持多环境参数化部署的完整示例，带你从"能用"走向"精通"。

一、Declarative Pipeline 的核心结构

声明式 Pipeline 是 Jenkins 推荐的结构化语法，具有严格的格式要求，适合新手快速上手。所有有效的声明式 Pipeline 必须包含在一个 pipeline 块中：

groovy 复制代码

pipeline {
    agent any      // 指定运行环境
    stages {       // 定义流程阶段
        stage('阶段名称') {
            steps { // 阶段内的具体步骤
                // 执行操作
            }
        }
    }
}

四大核心组件：

二、核心指令详解

2.1 agent：指定执行环境

agent 定义 Pipeline 在哪个 Jenkins 节点上运行：

groovy 复制代码

// 在任意可用节点运行
agent any

// 在指定标签的节点运行
agent { label 'build-node' }

// 在 Docker 容器中运行（最常用）
agent {
    docker {
        image 'maven:3.8.4-openjdk-17'
        args '-v /root/.m2:/root/.m2'
    }
}

💡 实践建议：对于 Java/Maven 项目，使用 Docker 容器作为 agent 可以保证构建环境的一致性。

2.2 environment：定义环境变量

environment 用于定义 Pipeline 中可用的环境变量：

groovy 复制代码

pipeline {
    agent any
    environment {
        APP_NAME = 'my-app'
        REGISTRY = 'registry.example.com'
        BUILD_ENV = 'production'
    }
    stages {
        stage('构建') {
            steps {
                echo "构建 ${env.APP_NAME} 版本 ${env.BUILD_ENV}"
            }
        }
    }
}

2.3 parameters：参数化构建

parameters 允许用户在触发构建时传入参数，使 Pipeline 更灵活：

groovy 复制代码

pipeline {
    agent any
    parameters {
        string(name: 'BRANCH', defaultValue: 'main', description: '要构建的分支')
        choice(name: 'ENV', choices: ['dev', 'test', 'prod'], description: '部署环境')
        booleanParam(name: 'SKIP_TESTS', defaultValue: false, description: '跳过测试')
    }
    stages {
        stage('构建') {
            steps {
                echo "构建分支: ${params.BRANCH}"
                echo "部署到: ${params.ENV}"
                if (params.SKIP_TESTS) {
                    echo '跳过测试'
                }
            }
        }
    }
}

2.4 triggers：自动触发

triggers 定义 Pipeline 的自动触发方式：

groovy 复制代码

pipeline {
    agent any
    triggers {
        // 每 5 分钟检查一次代码变更
        pollSCM('H/5 * * * *')
        // 每天凌晨 2 点定时执行
        cron('0 2 * * *')
    }
    stages {
        // ...
    }
}

2.5 when：条件执行

when 控制 Stage 在满足特定条件时才执行：

groovy 复制代码

pipeline {
    agent any
    stages {
        stage('部署到生产') {
            when {
                branch 'main'
                environment name: 'ENV', value: 'prod'
            }
            steps {
                echo '部署到生产环境...'
            }
        }
        stage('部署到开发') {
            when {
                expression { params.ENV == 'dev' }
            }
            steps {
                echo '部署到开发环境...'
            }
        }
    }
}

2.6 post：构建后处理

post 在 Pipeline 执行完毕后运行，无论成功还是失败：

groovy 复制代码

pipeline {
    agent any
    stages {
        // ...
    }
    post {
        success {
            echo '构建成功！'
        }
        failure {
            echo '构建失败！'
            // 发送告警通知
        }
        always {
            cleanWs()  // 清理工作空间
        }
    }
}

三、完整实战：多环境参数化部署 Pipeline

下面是一个完整的、可直接运行的 Jenkinsfile，集成了上述所有核心指令：

groovy 复制代码

pipeline {
    agent any

    // 全局环境变量
    environment {
        APP_NAME = 'my-app'
        REGISTRY = 'registry.example.com'
    }

    // 构建参数
    parameters {
        string(name: 'BRANCH', defaultValue: 'main', description: 'Git 分支')
        choice(name: 'ENV', choices: ['dev', 'staging', 'prod'], description: '部署环境')
        booleanParam(name: 'RUN_TESTS', defaultValue: true, description: '是否运行测试')
    }

复制代码

// 自动触发：每 10 分钟检查代码变更
triggers {
    pollSCM('H/10 * * * *')
}

// 定义流水线阶段
stages {
    stage('拉取代码') {
        steps {
            echo "从分支 ${params.BRANCH} 拉取代码..."
            // checkout scm  // 实际项目中启用
        }
    }

    stage('编译打包') {
        steps {
            echo '开始编译...'
            sh 'mvn clean package -DskipTests'
        }
    }

    stage('单元测试') {
        when {
            expression { params.RUN_TESTS == true }
        }
        steps {
            echo '运行单元测试...'
            sh 'mvn test'
        }
    }

    stage('构建镜像') {
        when {
            environment name: 'ENV', value: 'prod'
        }
        steps {
            echo "构建 Docker 镜像并推送到 ${env.REGISTRY}"
            sh """
                docker build -t ${env.REGISTRY}/${env.APP_NAME}:latest .
                docker push ${env.REGISTRY}/${env.APP_NAME}:latest
            """
        }
    }

    stage('部署') {
        steps {
            echo "部署 ${env.APP_NAME} 到 ${params.ENV} 环境..."
            // 实际项目中根据环境执行不同部署脚本
            sh "echo '部署到 ${params.ENV} 完成'"
        }
    }
}

// 构建后处理
post {
    success {
        echo "✅ Pipeline 执行成功！${env.APP_NAME} 已部署到 ${params.ENV}"
    }
    failure {
        echo "❌ Pipeline 执行失败！请检查日志。"
        // 可在此处发送邮件或 Slack 告警
    }
    always {
        echo '清理工作空间...'
        cleanWs()
    }
}

}

四、Pipeline as Code 最佳实践

4.1 将 Jenkinsfile 存入代码仓库

将上述 Jenkinsfile 保存为项目根目录下的 Jenkinsfile，并提交到 Git 仓库。

4.2 配置 Jenkins 从 SCM 读取 Pipeline

在 Jenkins 任务配置中：

选择 "流水线" → "Pipeline script from SCM"

SCM 选择 Git

填写仓库地址和凭证

Script Path 填写 Jenkinsfile

4.3 多分支流水线

对于多分支项目，推荐使用 "多分支流水线" （Multibranch Pipeline）任务类型。它会自动扫描 Git 仓库的所有分支，为每个分支创建对应的 Pipeline，并自动触发构建。

五、小结

Declarative Pipeline 是 Jenkins 推荐的结构化语法，适合新手快速上手

核心指令：agent（执行环境）、environment（环境变量）、parameters（参数化构建）、triggers（自动触发）、when（条件执行）、post（构建后处理）

最佳实践：将 Jenkinsfile 存入代码仓库，使用多分支流水线实现分支自动构建