4. Jenkins Pipeline 基础：声明式 Pipeline 语法、Stage 与 Step 详解

声明式 Pipeline（Declarative Pipeline）是 Jenkins 2.x 引入的流水线定义方式，它提供了一种结构化、更易读的语法来定义持续交付流水线。与脚本式 Pipeline（Scripted Pipeline）相比，声明式 Pipeline 强制使用 pipeline 块作为顶层结构，并通过 agent、stages、post 等指令明确划分职责，非常适合团队协作与版本化管理。

4.1 声明式 Pipeline 的骨架结构

一个完整的声明式 Pipeline 由以下核心块组成：

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Test') {
            steps {
                echo 'Testing...'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying...'
            }
        }
    }

    post {
        always {
            echo 'This will always run'
        }
        success {
            echo 'This will run only if successful'
        }
        failure {
            echo 'This will run only if failed'
        }
    }
}

4.2 Stage 与 Step 的深度解析

Stage（阶段）是流水线的逻辑分割点，通常对应 CI/CD 流程中的一个关键环节，例如编译、单元测试、集成测试、部署。每个 stage 必须有一个唯一的名称，并且可以嵌套 when 条件、environment 变量、tools 等指令。

Step（步骤）是 stage 内可执行的最小操作单元。Jenkins 提供了数百种内置步骤（如 sh、echo、git、docker），同时 Pipeline 插件也可以扩展自定义步骤。

以下是一个包含多步骤的典型阶段示例：

stage('Build & Unit Test') {
    steps {
        echo 'Checking out source code...'
        checkout scm

        echo 'Installing dependencies...'
        sh 'npm install'

        echo 'Running unit tests...'
        sh 'npm test'

        echo 'Building artifact...'
        sh 'npm run build'
    }
}

4.3 声明式 Pipeline 核心指令速查

4.4 声明式 Pipeline 执行流程示意图

下图展示了声明式 Pipeline 从触发到完成的完整执行路径，重点突出 stages 与 post 的关系：

4.5 实战：多环境蓝绿发布中的 Stage 设计

在蓝绿发布场景中，声明式 Pipeline 的 stage 设计需要兼顾环境切换、健康检查和回滚能力。以下是一个典型的蓝绿发布流水线阶段划分：

1. Checkout — 从 Git 仓库拉取指定分支代码。
2. Build — 编译代码并生成 Docker 镜像，打上版本标签。
3. Unit Test — 执行单元测试，失败则中止流水线。
4. Deploy to Blue — 将新版本部署到蓝环境（当前空闲环境）。
5. Smoke Test — 对蓝环境执行冒烟测试，验证基本功能。
6. Switch Traffic — 将负载均衡流量从绿环境切换到蓝环境。
7. Health Check — 持续监控新环境 5 分钟，确认无异常。
8. Cleanup Old — 销毁旧绿环境，释放资源。

4.6 声明式 vs 脚本式 Pipeline 对比

4.7 使用 when 指令实现条件化阶段

在蓝绿发布中，某些阶段可能只在特定分支或特定条件下执行。声明式 Pipeline 的 when 指令可以优雅地解决这个问题：

stage('Deploy to Production') {
    when {
        branch 'main'
        expression { return env.DEPLOY_ENV == 'production' }
    }
    steps {
        echo 'Deploying to production environment...'
        sh './deploy-prod.sh'
    }
}

when 支持多种内置条件：branch、environment、expression、not、allOf、anyOf，可以组合使用实现复杂的触发逻辑。

4.8 声明式 Pipeline 中的环境变量与 Secrets 注入

在蓝绿发布场景中，不同环境（蓝/绿）通常需要不同的配置和密钥。声明式 Pipeline 支持在 environment 块中定义变量，并配合 Jenkins Credentials 插件安全注入 Secrets：

pipeline {
    agent any

    environment {
        // 从 Jenkins 凭据存储中安全获取
        DOCKER_REGISTRY_CREDS = credentials('docker-registry-credentials')
        // 普通环境变量
        APP_VERSION = '1.3.0'
    }

    stages {
        stage('Deploy to Blue') {
            environment {
                TARGET_ENV = 'blue'
                DB_PASSWORD = credentials('blue-db-password')
            }
            steps {
                sh '''
                    docker login --username=$DOCKER_REGISTRY_CREDS_USR \
                                 --password=$DOCKER_REGISTRY_CREDS_PSW
                    docker-compose -f docker-compose-$TARGET_ENV.yml up -d
                '''
            }
        }
    }
}

使用 credentials() 方法时，Jenkins 会自动生成两个变量：变量名_USR（用户名）和 变量名_PSW（密码），确保敏感信息不会明文出现在日志中。

4.9 常见错误与调试技巧

• 语法错误：声明式 Pipeline 对缩进和括号敏感，建议在 Jenkins 的 Pipeline Syntax 工具中验证代码。
• 步骤未找到：某些步骤需要安装对应的 Pipeline 插件（如 docker 步骤需要 Docker Pipeline 插件）。
• 环境变量未生效：检查变量作用域——environment 定义在 pipeline 级别为全局，定义在 stage 级别仅在该阶段有效。
• 并行阶段死锁：使用 parallel 时确保每个分支不竞争同一资源（如文件锁、端口）。