Jenkins流水线Pipeline声明式语法基础入门----下

Options（可选）：全局/局部配置

作用：配置流水线的全局或局部选项，用于提升流水线的稳定性、可维护性，如超时控制、日志设置、构建历史保留等。

常用参数及用法（全局+局部结合）：

pipeline {
    agent any
    // 全局options：对整个流水线生效（所有stage）
    options {
        timestamps() // 日志添加时间戳，便于问题排查（推荐必加）
        timeout(time: 1, unit: 'HOURS') // 全局超时：整个流水线执行超过1小时自动终止
        buildDiscarder(logRotator(numToKeepStr: '10')) // 保留最近10次构建历史，节省磁盘空间
        disableConcurrentBuilds() // 禁止并行构建，避免多个流水线同时执行导致资源冲突
        skipDefaultCheckout(true) // 可选：跳过默认的代码拉取步骤（若手动配置git指令，建议开启）
    }
    stages {
        stage('代码拉取') {
            // 局部options：仅对当前stage生效，优先级高于全局options
            options {
                timeout(time: 5, unit: 'MINUTES') // 当前阶段超时5分钟，覆盖全局超时
            }
            steps {
                git url: 'https://gitee.com/xxx/demo-service.git', branch: 'dev'
            }
        }
    }
}

参数说明：

• timestamps()：无参数，日志每一行都会添加时间戳，便于排查构建失败的时间点。

• timeout(time: 数值, unit: '单位')：超时控制，unit支持SECONDS（秒）、MINUTES（分钟）、HOURS（小时）。

• buildDiscarder(logRotator(numToKeepStr: '数值'))：保留指定次数的构建历史，numToKeepStr为字符串类型（如'10'），避免构建日志过多占用磁盘。

• disableConcurrentBuilds()：无参数，禁止同一流水线同时执行多个构建任务，避免资源竞争。

• skipDefaultCheckout(true)：跳过Jenkins默认的代码拉取步骤，若手动配置git指令，建议开启，避免重复拉取。

2.5 Environment（可选）：环境变量配置

作用：定义全局或局部环境变量，用于统一管理配置（如项目名称、版本号、路径），避免硬编码，提升脚本复用性和可维护性。

常用参数及用法（全局+局部结合）：

pipeline {
    agent any
    // 全局环境变量：所有stage均可引用
    environment {
        APP_NAME = 'demo-service' // 项目名称（自定义变量）
        JDK_PATH = '/usr/lib/jvm/java-11-openjdk' // JDK路径（自定义变量）
        BUILD_VERSION = '1.0.0' // 构建版本号（自定义变量）
        // 引用Jenkins内置环境变量（无需定义，直接使用）
        // 常用内置变量：env.BUILD_NUMBER（构建次数）、env.BRANCH_NAME（当前分支）
    }
    stages {
        stage('测试环境变量') {
            // 局部环境变量：仅当前stage生效，覆盖全局同名变量
            environment {
                BUILD_VERSION = '1.0.1' // 覆盖全局版本号
            }
            steps {
                // 引用环境变量：使用${变量名}
                echo "项目名称：${APP_NAME}"
                echo "JDK路径：${JDK_PATH}"
                echo "当前版本：${BUILD_VERSION}" // 输出1.0.1（局部覆盖全局）
                echo "构建次数：${env.BUILD_NUMBER}" // 引用内置环境变量
                // 动态修改环境变量（仅当前stage生效）
                env.BUILD_VERSION = '1.0.2'
                echo "修改后版本：${BUILD_VERSION}" // 输出1.0.2
            }
        }
    }
}

参数说明：

• 自定义变量：格式为「变量名 = '值'」，值为字符串类型，可引用其他环境变量（如 BUILD_VERSION = "1.0.${env.BUILD_NUMBER}"）。

• 内置环境变量：Jenkins自带，无需定义，直接通过env.变量名引用，常用内置变量：

  • env.BUILD_NUMBER：当前构建次数（自增整数）。

  • env.BRANCH_NAME：当前构建的分支名称。

  • env.JOB_NAME：当前流水线的名称。

• 局部环境变量：在stage内部配置，仅对当前stage生效，若与全局变量同名，会覆盖全局变量。

易错点：环境变量名称不能包含空格、特殊字符，建议用大写+下划线（如APP_NAME），避免语法错误。

pipeline {
    tools {
        maven 'maven'
        jdk 'java'
        nodejs 'node'
    }
    environment {
        NPM_CONFIG_REGISTRY = 'https://registry.npmmirror.com/'
        GIT_URL = 'git@gitee.com:testpm/frontend-demo.git'
        GIT_ID = 'jenkins-slave-git' 
    }
    agent {
        node {
            label 'jenkins-slave'
            customWorkspace '/home/jenkins/data'
        }
    }
    options {
        timestamps()
        timeout(time: 1, unit: 'HOURS')
        buildDiscarder(logRotator(numToKeepStr: '10'))
    }
    stages {
        stage('获取代码') {
            options {
                timeout(time: 5, unit: 'MINUTES')
            }
            steps {
                git url: "${GIT_URL}",
                branch: 'master',
                credentialsId: "${GIT_ID}"
            }
        }
        stage('安装依赖') {
            steps {
                echo '显示当前所在目录'
                sh 'pwd'
                echo '清理旧依赖...'
                sh 'rm -rf node_modules package-lock.json'
                sh 'npm cache clean --force'
                echo '安装依赖...'
                sh 'npm install --legacy-peer-deps'
            }
        }
        stage('编译构建') {
            steps {
                timeout(time: 15, unit: 'MINUTES') {
                sh 'npm run build'
                echo '构建完成，dist目录内容：'
                sh 'ls -la dist/'
                }
            }
        }
    }
}

Jenkins Pipeline 变量 + 凭据（Docker/Git）完整用法

变量怎么定义 、Docker 仓库地址 / 账号密码怎么存 、Git 凭据怎么用变量引用。

全程使用 Jenkins 官方最佳实践：凭据存在 Jenkins 里，Pipeline 只用变量名引用，不写明文！

一、先搞懂 2 种变量（Pipeline 必用）

1. 普通变量（存放地址、常量）

适合：Docker 仓库地址、Git 地址、镜像名、版本号等不敏感内容

DOCKER_REGISTRY = 'harbor.example.com'
GIT_REPO_URL = 'http://git.example.com/my/project.git'
IMAGE_NAME = 'my-app'

2. 凭据变量（存放密码、token）

适合：Docker 登录账号密码、Git 账号密码、私有令牌

必须存在 Jenkins 凭据里，不能写代码里！

二、第一步：在 Jenkins 里创建凭据（最重要）

进入：Jenkins 首页 → 凭据 → 系统 → 全局凭据 → 添加凭据

需要创建 1个凭据：

1）Docker 登录凭据（账号 + 密码）

• 类型：Username with password
• ID：docker-login（记住这个 ID，Pipeline 要用）
• 用户名：Docker 仓库账号
• 密码：Docker 仓库密码

三、Pipeline 中定义变量 + 使用凭据（完整可运行）

标准生产可用模板：

pipeline {
    agent any
    tools {
        jdk 'java17'
        maven 'maven39'
    }
    environment {
        // ====================== 1. 普通变量（地址、常量）======================
        DOCKER_REGISTRY = 'harbor.example.com'      // Docker 仓库地址
        DOCKER_IMAGE_NAME = 'my-project/app'        // 镜像名
        GIT_URL = 'http://git.example.com/my/app.git' // Git 地址

        // ====================== 2. 凭据变量（账号密码，引用 Jenkins 凭据 ID）======================
        DOCKER_CRED = credentials('docker-login')   // 引用 Docker 凭据 ID
    }
    stages {
        stage('拉代码') {
            steps {
                // ====================== 使用 Git 凭据变量 ======================
                git url: "${GIT_URL}", 
                    credentialsId: "git-login", 
                    branch: 'main'
            }
        }

        stage('构建') {
            steps {
                sh 'mvn clean package -DskipTests'
            }
        }

        stage('构建镜像') {
            steps {
                // ====================== 使用 Docker 变量 ======================
                sh '''
                    docker build -t ${DOCKER_REGISTRY}/${DOCKER_IMAGE_NAME}:${BUILD_NUMBER} .
                '''
            }
        }

        stage('登录Docker仓库') {
            steps {
                // ====================== 使用 Docker 登录凭据（账号密码自动注入）======================
                sh '''
                    echo ${DOCKER_CRED_PSW} | docker login ${DOCKER_REGISTRY} \
                        -u ${DOCKER_CRED_USR} \
                        --password-stdin
                '''
            }
        }

        stage('推送镜像') {
            steps {
                sh '''
                    docker push ${DOCKER_REGISTRY}/${DOCKER_IMAGE_NAME}:${BUILD_NUMBER}
                '''
            }
        }
    }
}

凭据变量自动生成 3 个值

当你写：

DOCKER_CRED = credentials('docker-login')

Jenkins 自动生成 3 个变量：

• ${DOCKER_CRED} → 账号：密码
• ${DOCKER_CRED_USR} → 仅账号
• ${DOCKER_CRED_PSW} → 仅密码

后缀 _USR 和 _PSW 是 Jenkins 固定规则 ，不能改！因为前面的名字是你定的，后面的 _USR /_PSW 是 Jenkins 强制加的固定后缀。

credentials() 函数的正确用法

• 作用 ：从 Jenkins 凭证管理中读取凭证，返回对应类型的对象（usernamePassword 类型返回 username/password 对象，string 类型返回字符串）。
• 适用场景 ：需要在脚本中使用凭证的实际内容（如密码、Token），而不是仅用 ID。

Docker 登录（最常用）

echo ${DOCKER_CRED_PSW} | docker login ${DOCKER_REGISTRY} -u ${DOCKER_CRED_USR} --password-stdin

Git 拉代码带凭据

git url: "${GIT_URL}", credentialsId: "git-login", branch: "main"

拼接 Docker 完整镜像地址

${DOCKER_REGISTRY}/${DOCKER_IMAGE_NAME}:${BUILD_NUMBER}

总结一句话记住

1. 不敏感内容 → 直接定义 environment 变量
2. 账号密码 → 存在 Jenkins 凭据，用 credentials('ID') 引用
3. Docker 登录 → 使用 ${XXX_USR} 和 ${XXX_PSW}
4. Git 拉代码 → 使用 credentialsId: '凭据ID'

Docker 登录（最常用）

echo ${DOCKER_CRED_PSW} | docker login ${DOCKER_REGISTRY} -u ${DOCKER_CRED_USR} --password-stdin

Git 拉代码带凭据

git url: "${GIT_URL}", credentialsId: "git-login", branch: "main"

拼接 Docker 完整镜像地址

${DOCKER_REGISTRY}/${DOCKER_IMAGE_NAME}:${BUILD_NUMBER}

2.6 Post（可选）：构建后处理

作用：放在pipeline根节点下，用于构建完成后的统一处理，无论构建成功、失败、被终止，都能执行相应逻辑，是流水线的"收尾工作"，提升流水线的完整性。

常用参数及用法（覆盖所有构建结果）：

pipeline {
    agent any
    stages {
        stage('构建') {
            steps {
                sh 'mvn clean package' // 模拟构建，若失败则触发failure
            }
        }
    }
    // post块：构建后处理，放在pipeline根节点下，在所有stage执行完成后执行
    post {
        // 1. success：构建成功时执行
        success {
            echo '✅ 构建成功！'
            archiveArtifacts artifacts: 'target/*.jar' // 归档构建产物
        }
        // 2. failure：构建失败时执行（如步骤报错、超时）
        failure {
            echo '❌ 构建失败，请及时排查！'
            // 可选：发送失败通知（钉钉/企业微信，需配合插件）
            // dingtalkSend robot: 'dingtalk-robot', text: "构建失败：${env.JOB_NAME} #${env.BUILD_NUMBER}"
        }
        // 3. aborted：流水线被手动终止时执行
        aborted {
            echo '🛑 流水线被手动终止'
        }
        // 4. always：无论构建结果如何，都执行（推荐必加，用于清理工作空间）
        always {
            cleanWs() // 清理工作空间，避免残留文件
            echo '工作空间清理完成，流水线执行结束'
        }
        // 5. changed：构建结果与上一次相比发生变化时执行（如上次失败，本次成功）
        changed {
            echo '⚠️  构建结果发生变化，请关注！'
        }
    }
}

参数说明：

• success：仅当所有stage都执行成功，构建状态为SUCCESS时触发。

• failure：只要有一个stage执行失败，或流水线超时、报错，构建状态为FAILURE时触发。

• aborted：用户手动点击"终止构建"，构建状态为ABORTED时触发。

• always：无论构建状态是SUCCESS、FAILURE、ABORTED，都会触发，优先级最低，适合做清理、归档操作。

• changed：仅当本次构建结果与上一次构建结果不同时触发（如上次失败，本次成功；上次成功，本次失败）。

易错点：post块必须放在pipeline根节点下，不能放在stage内部；post块内的执行顺序为：success/failure/aborted → changed → always。

案例

pipeline {
    tools {
        maven 'maven'
        jdk 'java'
        nodejs 'node'
    }
    environment {
        NPM_CONFIG_REGISTRY = 'https://registry.npmmirror.com/'
        GIT_URL = 'git@gitee.com:testpm/frontend-demo.git'
        GIT_ID = 'jenkins-slave-git' 
    }
    agent {
        node {
            label 'jenkins-slave'
            customWorkspace '/home/jenkins/data'
        }
    }
    options {
        timestamps()
        timeout(time: 1, unit: 'HOURS')
        buildDiscarder(logRotator(numToKeepStr: '10'))
    }
    stages {
        stage('获取代码') {
            options {
                timeout(time: 5, unit: 'MINUTES')
            }
            steps {
                git url: "${GIT_URL}",
                branch: 'master',
                credentialsId: "${GIT_ID}"
            }
        }
        stage('安装依赖') {
            steps {
                echo '显示当前所在目录'
                sh 'pwd'
                echo '清理旧依赖...'
                sh 'rm -rf node_modules package-lock.json'
                sh 'npm cache clean --force'
                echo '安装依赖...'
                sh 'npm install --legacy-peer-deps'
            }
        }
        stage('编译构建') {
            steps {
                timeout(time: 15, unit: 'MINUTES') {
                sh 'npm run build'
                echo '构建完成，dist目录内容：'
                sh 'ls -la dist/'
                echo '正在归档'
                archiveArtifacts artifacts: 'dist/**',
                allowEmptyArchive: true
                }
            }
        }
    }
    post {
        success {
            echo '✅ 构建成功！'
        }
        changed {
            echo '⚠️  构建结果发生变化，请关注！'
        }
        aborted {
            echo '🛑 流水线被手动终止'
        }
        always {
            cleanWs()
            echo '工作空间清理完成，流水线执行结束'
        }
    }
}

注意当我们使用archiveArtifacts artifacts归档参数的时候，最终会以压缩包形式存储在 Jenkins 服务器的任务工作区和归档目录两个位置，同时可以在 Jenkins 页面直接下载。

一、核心存储位置（按优先级）

1. 【最常用】Jenkins 页面直接下载（无需登录服务器）
   这是最方便的方式，归档完成后：
   进入你的 Jenkins 任务 → 点击本次构建（Build History 里的编号）
   左侧菜单会出现 #构建号 → 点击 Artifacts
   就能看到完整的 dist 目录结构，可直接下载单个文件或整个目录（浏览器会自动打包为 ZIP）

2. 【服务器物理路径】Jenkins 归档目录（永久存储）

   归档的压缩包会永久保存在 Jenkins 主目录下，即使清理工作空间也不会删除，路径格式为：

   ${JENKINS_HOME}/jobs/${任务名}/builds/${构建号}/archive/
   
   [root@jenkins archive]# ls
   dist
   [root@jenkins archive]# pwd
   /root/.jenkins/jobs/frontend-demo/builds/43/archive

二、补充说明（你关心的压缩包问题）

1. 归档是「按目录结构存储」，不是单个大压缩包
   Jenkins 的 archiveArtifacts 不会把 dist 打成一个 .zip 包存服务器，而是：
   把 dist 下的所有文件、子目录原封不动复制到 archive/ 目录,当你在页面点击下载时，Jenkins 才会实时打包成 ZIP 供下载,服务器上存储的是解压后的完整目录结构，方便直接查看、部署
2. 如果你想「生成单个压缩包」归档,如果需要把 dist 打成一个 .zip 包再归档，在流水线中添加打包步骤即可：

#打包步骤（放在 npm run build 之后，archiveArtifacts 之前）
sh 'zip -r dist.zip dist/'
#归档单个 zip 包
archiveArtifacts artifacts: 'dist.zip', allowEmptyArchive: true
#这样归档后，服务器上就会有一个 dist.zip 文件，路径为：
${JENKINS_HOME}/jobs/任务名/builds/构建号/archive/dist.zip

未完待续...