Pipeline 语法参考

本篇是声明式 Pipeline 的语法速查手册，汇总所有指令、区块和常用步骤的写法。适合边写边查，不必一次读完。

前置：先看第 5 篇（Groovy 基础）和第 6、7 篇（声明式基础与进阶）。

---

1. Pipeline 顶层结构

pipeline {
    agent any                    // 在哪个节点运行
    options { ... }              // 流水线级选项
    triggers { ... }             // 触发方式
    parameters { ... }           // 参数化构建
    environment { ... }          // 环境变量
    tools { ... }                // 工具链
    stages { ... }               // 阶段（必填，至少一个）
    post { ... }                 // 收尾动作
}

指令	作用	必填
agent	指定执行节点/容器	✅
stages	定义阶段序列	✅
steps	阶段内的具体步骤	在 stage 内必填
environment	环境变量	可选
options	流水线级选项	可选
parameters	参数化构建	可选
triggers	定时/Webhook 触发	可选
post	构建后收尾	可选

---

2. agent：运行位置

agent any                                  // 任意节点
agent none                                 // 顶层不指定，各 stage 指定
agent { label 'linux && jdk17' }           // 按标签
agent { docker { image 'maven:3.9' } }     // Docker 容器
agent {
    docker {
        image 'maven:3.9'
        args '-v /opt/m2:/root/.m2'        // 额外参数
    }
}
agent {
    kubernetes { yaml '''...''' }          // K8s 动态 Pod
}

// stage 级覆盖
stage('Test') {
    agent { label 'test-node' }
    steps { sh 'mvn test' }
}

---

3. options：流水线级选项

options {
    timestamps()                                        // 日志加时间戳
    timeout(time: 1, unit: 'HOURS')                     // 总超时
    buildDiscarder(logRotator(numToKeepStr: '30'))      // 构建保留策略
    disableConcurrentBuilds()                           // 禁止并发
    skipDefaultCheckout()                               // 跳过自动 checkout
    skipStagesAfterUnstable()                           // unstable 后跳过
    ansiColor('xterm')                                  // ANSI 彩色日志
    retry(3)                                            // 整体重试次数
    parallelsAlwaysFailFast()                           // 并行全失败即停
}

常用单位：NANOSECONDS、MICROSECONDS、MILLISECONDS、SECONDS、MINUTES、HOURS、DAYS。

---

4. parameters：参数化构建

parameters {
    string(name: 'IMAGE_TAG', defaultValue: '', description: '镜像版本')
    booleanParam(name: 'DEPLOY', defaultValue: false, description: '是否部署')
    choice(name: 'ENV', choices: ['dev', 'staging', 'prod'], description: '环境')
    text(name: 'NOTES', defaultValue: '', description: '备注')
    password(name: 'DB_PASS', defaultValue: '', description: '数据库密码')
    file(name: 'CONFIG_FILE', description: '上传配置文件')
}

类型	引用方式
所有类型	params.XXX
环境变量方式	env.XXX（部分类型可用）

stage('显示参数') {
    steps { echo "环境=${params.ENV}, 部署=${params.DEPLOY}" }
}

---

5. triggers：触发方式

triggers {
    pollSCM('H/5 * * * *')                  // 轮询代码变更
    cron('H 2 * * *')                       // 定时构建
    upstream(upstreamProjects: 'job-a, job-b', threshold: hudson.model.Result.SUCCESS)  // 上游完成触发
    // Webhook 触发在 Job 配置或插件 DSL 中配置
}

---

6. environment：环境变量

environment {
    APP_NAME = 'backend'                    // 静态值
    IMAGE = "${REGISTRY}/${APP_NAME}:v${BUILD_NUMBER}"
    DOCKER_CREDS = credentials('harbor-registry-auth')   // 凭证绑定（见第 4 篇）
}
// stage 级 environment 只在该 stage 生效
stage('Build') {
    environment { JAVA_OPTS = '-Xmx1g' }
    steps { ... }
}

内置变量速查：

变量	含义
BUILD_NUMBER	构建序号
BUILD_URL	构建页面 URL
JOB_NAME	Job 全名
JOB_BASE_NAME	Job 短名
WORKSPACE	工作目录
GIT_COMMIT	提交 SHA
GIT_BRANCH	分支名
GIT_TAG	当前 Tag（如有）
BRANCH_NAME	多分支中的分支名

---

7. stages / stage / steps

stages {
    stage('Build') {
        steps {
            echo '...'
            sh 'mvn package'
        }
    }
    stage('Test') {
        // 并行子 stage
        parallel {
            stage('Unit') { steps { sh 'mvn test -Dgroups=unit' } }
            stage('IT')   { steps { sh 'mvn test -Dgroups=it' } }
        }
    }
    stage('Deploy') {
        when { branch 'main' }        // 条件
        steps { sh 'kubectl apply' }
    }
}

stage 内还可以有：agent、environment、when、input、post、tools、options（stage 级）。

---

8. when：条件执行

when {
    branch 'main'                                    // 分支名（可通配 'release-*'）
    branch pattern: 'PR-*', comparator: 'REGEXP'     // 正则
    environment name: 'ENV', value: 'prod'           // 环境变量
    expression { return params.DEPLOY == true }      // Groovy 表达式
    tag pattern: 'v\\d+.*', comparator: 'REGEXP'     // 匹配 Tag
    changeset '**/*.java'                            // 指定文件变更
    changeRequest()                                  // 是 PR/MR
    beforeAgent true                                 // 分配 Agent 前判断
    allOf { branch 'main'; environment ... }         // 全部满足
    anyOf { branch 'main'; tag 'v1.*' }              // 任一满足
    not { branch 'main' }                            // 取反
}

---

9. input：人工确认

stage('确认部署') {
    input {
        message "确认部署到生产？"
        ok "确认"
        submitter "admin,ops"                        // 仅允许这些人审批
        parameters { string(name: 'APPROVER', defaultValue: '', description: '审批人') }
    }
    steps { sh 'kubectl apply -f deploy/prod/' }
}

---

10. post：构建后收尾

post {
    always { echo '无论结果都执行' }          // 清理、归档
    success { echo '成功' }
    unstable { echo '不稳定' }
    failure { echo '失败' }
    aborted { echo '被取消' }
    notBuilt { echo '未执行' }
    changed { echo '结果与上次不同' }         // 变化才通知
    fixed { echo '上次失败本次成功' }
    regression { echo '上次成功本次失败' }
    cleanup { cleanWs() }                     // 在 always 后执行清理
}

执行顺序：always → changed/fixed/regression → success/unstable/failure/aborted/notBuilt → cleanup。

---

11. 常用步骤（Steps）

11.1 命令与脚本

步骤	说明
sh 'cmd'	执行 shell 命令
bat 'cmd'	Windows 批处理
powershell 'cmd'	PowerShell
echo 'text'	打印日志

sh 'mvn clean package'
sh """
    export VERSION=v${BUILD_NUMBER}
    docker build -t \$IMAGE .
"""
// 返回命令输出
def out = sh(script: 'git rev-parse --short HEAD', returnStdout: true).trim()
echo "短 SHA: ${out}"

11.2 文件与目录

步骤	说明
dir('sub') { ... }	切换子目录执行
writeFile file: 'x.txt', text: '...'	写文件
readFile 'x.txt'	读文件
fileExists 'path'	判断文件存在
deleteDir()	清空当前目录
cleanWs()	清空整个 Workspace
findFiles	查找文件

dir('sub-module') {
    sh 'mvn package'
    def p = readFile('pom.xml')
}

11.3 凭证与密钥

withCredentials([usernamePassword(
    credentialsId: 'harbor-auth',
    usernameVariable: 'REG_USER',
    passwordVariable: 'REG_PASS'
)]) {
    sh 'docker login -u $REG_USER -p $REG_PASS registry.com'
}

withCredentials([string(credentialsId: 'gitlab-token', variable: 'TOKEN')]) {
    sh 'curl -H "PRIVATE-TOKEN: $TOKEN" ...'
}

withCredentials([file(credentialsId: 'kubeconfig', variable: 'KUBECONFIG')]) {
    sh 'kubectl --kubeconfig $KUBECONFIG get pods'
}

11.4 Git 与 SCM

步骤	说明
checkout scm	检出当前仓库（多分支自动）
git 'https://...'	简化的 git 检出
git branch: 'main', url: '...', credentialsId: '...'	带凭证检出
sh 'git ...'	任意 git 命令

checkout([
    $class: 'GitSCM',
    branches: [[name: '*/main']],
    userRemoteConfigs: [[url: 'https://git.company.com/team/app.git']],
    extensions: [[$class: 'SubmoduleOption', disableSubmodules: true]]
])

11.5 归档与制品

archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
junit 'target/surefire-reports/*.xml'     // 收集测试报告
stash name: 'build', includes: 'target/**'      // 暂存（跨 stage/agent）
unstash 'build'

11.6 部署与云

docker.withRegistry('https://registry.com', 'harbor-auth') {
    docker.build("app:${env.BUILD_NUMBER}").push()
}
kubernetesDeploy(
    kubeconfigId: 'kubeconfig',
    configs: 'deploy/',
    enableConfigSubstitution: true
)

---

12. 常用内置函数与 API

// 构建结果
currentBuild.currentResult        // SUCCESS / UNSTABLE / FAILURE / ABORTED
currentBuild.displayName          // 构建显示名（可改）
currentBuild.description          // 构建描述
currentBuild.buildVariables       // 构建变量 Map

// 工具定位
tool 'Maven-3.9'                  // 返回工具路径
tool 'JDK-17'

// 暂停与等待
sleep time: 10, unit: 'SECONDS'
waitUntil { ... }                 // 轮询等待条件
timeout(time: 1, unit: 'MINUTES') { ... }

// 常用：等待集群部署就绪
timeout(time: 5, unit: 'MINUTES') {
    waitUntil {
        def ready = sh(
            script: "kubectl -n prod rollout status deploy/backend --timeout=10s",
            returnStatus: true   // 返回退出码不抛异常
        ) == 0
        return ready
    }
}

---

13. 排障速查

报错	原因与处理
No such DSL method 'xxx'	步骤拼写错误 / 插件未装 / 步骤放错层级
Method too large	单个 steps 块太大，拆成共享库步骤
Compilation error	Groovy 语法错误，看 script 块
Scripts not permitted	沙箱拦截，Manage Jenkins → In-process Script Approval 批准
Fatal: Could not create workspace	Agent Workspace 权限 / 磁盘问题
sh: xxx: command not found	Agent 缺工具，检查 tools / 镜像

---

14. 练习与验收

练习 A

1. 用 when { branch } + expression 组合实现"main 分支且带参数才部署"
2. 用 input 加审批门，限定 submitter
3. 用 post { changed } 实现结果变化才通知

练习 B

1. 用 sh(returnStdout: true) 获取命令输出并打印
2. 用 stash / unstash 把产物跨 stage 传递
3. 用 waitUntil + timeout 轮询等待一个资源就绪

验收清单

• 能用 agent / options / parameters / environment / triggers 各指令
• 会用 when 的 branch / environment / expression / allOf / not
• 会用 input 做人工审批
• 理解 post 的执行顺序和 changed / fixed / cleanup
• 掌握 sh / dir / withCredentials / stash 等常用步骤
• 会使用 currentBuild 内置对象和 timeout / waitUntil

下一篇：多分支流水线。