18.3.1 Pipeline语法基础与Jenkinsfile结构

Pipeline概念与运行机制#

Pipeline是Jenkins的流水线编排模型，通过代码定义从构建、测试到发布的完整流程。流水线在Jenkins中以Stage为可视化单元，执行由Agent承载，步骤由Step组成，支持持续集成与交付的可重复执行。

原理草图（从Jenkinsfile到执行器）：

Jenkinsfile位置与生命周期#

Jenkinsfile通常放在代码仓库根目录，作为流水线即代码的核心文件，随代码版本化管理。典型生命周期包括：拉取代码 → 解析Jenkinsfile → 分配Agent → 依次执行Stages → 归档与通知。

仓库结构示例：

repo/
├── Jenkinsfile
├── src/
└── README.md

生命周期关键日志定位命令（控制台输出中检索阶段）：

# 在构建控制台中查找关键阶段
grep -n "Stage" /var/lib/jenkins/jobs/demo/builds/1/log

Jenkinsfile基础结构#

Declarative Pipeline的基本骨架如下：
- pipeline：根块，定义流水线
- agent：执行节点，支持any/label/docker/kubernetes
- stages：阶段集合
- stage：单个阶段
- steps：阶段内执行步骤

完整可执行示例（根目录 Jenkinsfile）：

pipeline {
  agent any
  options {
    timeout(time: 20, unit: 'MINUTES')
    buildDiscarder(logRotator(numToKeepStr: '20'))
  }
  environment {
    APP_NAME = "demo-app"
  }
  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }
    stage('Build') {
      steps {
        sh 'echo "Building ${APP_NAME}"'
      }
    }
    stage('Test') {
      steps {
        sh 'echo "Running tests"'
      }
    }
  }
  post {
    success {
      archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true
    }
    failure {
      mail to: 'devops@example.com', subject: 'Build Failed', body: 'Check Jenkins console output.'
    }
    always {
      cleanWs()
    }
  }
}

核心语法要点#

agent：指定运行环境与节点策略
stages：定义流水线阶段与执行顺序
steps：执行shell、bat、script等
post：定义成功/失败/始终执行的后置动作
options：构建超时、日志保留、并发控制
environment：全局或阶段级环境变量
parameters：构建参数化入口
tools：配置JDK/Maven等工具链

语法片段示例（参数+工具链）：

parameters {
  string(name: 'BRANCH', defaultValue: 'main', description: 'Git branch')
  booleanParam(name: 'RUN_TEST', defaultValue: true, description: 'Run tests')
}
tools {
  jdk 'jdk11'
  maven 'maven3'
}

常用Step示例#

sh/bat：执行命令行
checkout/scm：检出代码
archiveArtifacts：归档制品
stash/unstash：跨节点传递文件
junit：测试报告收集
input：人工审批

示例：跨节点传递构建产物

stage('Build') {
  steps {
    sh 'mkdir -p dist && echo "binary" > dist/app.bin'
    stash name: 'app-bin', includes: 'dist/app.bin'
  }
}
stage('Deploy') {
  agent { label 'deploy-node' }
  steps {
    unstash 'app-bin'
    sh 'ls -l dist/'
  }
}

Jenkinsfile编写规范与最佳实践#

固定结构：pipeline → agent → options → environment → stages → post
阶段命名清晰，体现业务语义
关键步骤添加超时与重试控制
仅保留最小可用权限与凭据
使用流水线共享库抽象重复逻辑
与制品、镜像、版本号保持一致性

规范示例：超时与重试

stage('Build') {
  options { timeout(time: 10, unit: 'MINUTES') }
  steps {
    retry(2) {
      sh 'make build'
    }
  }
}

安装与前置配置（与本节相关）#

确保已安装Pipeline相关插件与Jenkins CLI（示例为LTS）：

# 1) 下载 jenkins-cli
curl -o jenkins-cli.jar http://jenkins.example.com/jnlpJars/jenkins-cli.jar

# 2) 安装必要插件（Pipeline）
java -jar jenkins-cli.jar -s http://jenkins.example.com/ \
  -auth admin:admin \
  install-plugin workflow-aggregator pipeline-stage-view git

# 3) 重启使插件生效
java -jar jenkins-cli.jar -s http://jenkins.example.com/ \
  -auth admin:admin safe-restart

创建流水线任务后选择“Pipeline script from SCM”，并填写仓库地址与凭据。

常见错误与排查方向#

语法错误：检查括号、缩进与指令位置
Agent不可用：确认节点标签与执行器资源
Step缺失：确认插件安装与版本
SCM拉取失败：检查凭据与网络
步骤超时：合理配置超时与分阶段拆分

排错命令示例：

# 检查节点在线状态（在节点机器）
systemctl status jenkins-agent

# 检查插件是否安装
java -jar jenkins-cli.jar -s http://jenkins.example.com/ \
  -auth admin:admin list-plugins | grep workflow

# SCM失败时测试网络连通性
git ls-remote https://github.com/example/repo.git

练习#

在新仓库中创建Jenkinsfile，包含Checkout/Build/Test三个Stage，并使用post归档产物。
增加参数BRANCH，实现可选择分支构建。
使用stash/unstash在两个不同label的Agent间传递构建文件。
故意写错一个指令（如stage写成stages），观察控制台错误并修复。

预期效果：
- 控制台输出显示各Stage顺序执行
- 构建完成后“Artifacts”可下载产物
- 失败时触发post中的failure分支