本文全方位整理Jenkins基础核心概念、两种流水线语法（声明式/脚本式）、核心指令、常用步骤、参数、触发器、环境配置、异常处理及实战规范，所有核心内容均以表格结构化展示，附带可直接复用的代码示例，适配CI/CD自动化落地场景。
一、Jenkins 基础核心知识点
1.1 Jenkins 核心概念汇总
| 核心概念 |
详细定义 |
核心作用 |
| Jenkins 核心定位 |
开源自动化CI/CD服务器，基于Java开发，跨平台、可扩展，支持插件化拓展功能 |
实现代码编译、构建、测试、打包、部署全流程自动化，提升研发交付效率 |
| Master节点 |
Jenkins主服务节点，负责任务调度、流水线管理、日志收集、配置存储 |
统一管控所有构建任务，不建议执行业务构建任务，避免性能瓶颈 |
| Agent节点（从节点） |
附属工作节点，支持Linux/Windows/Mac，可通过SSH、JNLP方式连接主节点 |
承接实际构建、部署任务，分布式执行，扩容构建能力，隔离构建环境 |
| Job/任务 |
Jenkins最小执行单元，分为自由风格项目、流水线项目、多分支流水线等类型 |
定义具体自动化流程，是CI/CD流程的载体 |
| Jenkinsfile |
流水线脚本文件，存储在项目代码仓库中，实现代码即流水线（Pipeline as Code） |
固化流水线配置，版本可控、可复用、团队协同统一，摒弃页面手动配置 |
| 插件体系 |
Jenkins核心拓展能力，官方及社区提供海量插件，覆盖代码拉取、构建、通知、部署等场景 |
弥补原生功能短板，适配Maven/Gradle/Docker/K8s等各类构建部署场景 |
| 构建历史 |
记录每一次任务执行的日志、状态、产物、耗时等信息，支持回溯、对比、重试 |
问题排查、流程优化、交付追溯的核心依据 |
1.2 Jenkins 两种流水线对比（核心重点）
Jenkins Pipeline 分为声明式流水线（Declarative） 和脚本式流水线（Scripted），生产环境优先使用声明式，规范度、兼容性、可读性更强。
| 对比维度 |
声明式流水线（Declarative） |
脚本式流水线（Scripted） |
| 语法基础 |
基于Groovy封装的结构化声明语法，固定格式、严格规范 |
原生Groovy脚本语法，完全兼容Groovy所有特性 |
| 学习难度 |
低，语法固定、约束强，新手易上手，报错提示清晰 |
高，需要掌握Groovy语法，灵活度高但无强制规范 |
| 结构规范性 |
强制固定结构（pipeline-agent-stages-steps-post），格式统一 |
自由编写，无固定结构，团队代码风格容易混乱 |
| 可维护性 |
高，结构化清晰、可读性强、便于迭代维护 |
较低，复杂脚本可读性差，维护成本高 |
| 灵活性 |
中等，标准化场景全覆盖，复杂逻辑可嵌套script块实现 |
极高，支持自定义函数、循环、递归、复杂流程控制 |
| 适用场景 |
90%企业CI/CD常规流程（构建、测试、打包、部署），生产首选 |
特殊复杂定制化流程、自定义流水线逻辑、高级脚本编排 |
二、声明式流水线完整语法详解（核心）
声明式流水线所有代码必须包裹在 pipeline {} 顶级块中，严格区分缩进（仅支持空格，不支持Tab），结构层级固定。
2.1 顶层核心模块总览
| 模块关键字 |
是否必填 |
作用位置 |
核心功能 |
| pipeline |
是 |
最顶层 |
流水线根节点，所有语法内容必须包含在此块内 |
| agent |
是 |
pipeline顶层 / stage层级 |
指定流水线/阶段的执行节点、容器环境 |
| stages |
是 |
pipeline顶层 |
承载所有业务阶段（stage），流水线核心执行主体 |
| stage |
是 |
stages内部 |
划分独立执行阶段（拉代码、构建、测试、部署等） |
| steps |
是 |
stage内部 |
每个阶段的具体执行命令、操作步骤 |
| post |
否 |
pipeline顶层 / stage层级 |
流水线/阶段执行完毕后的后置操作（通知、清理、归档） |
| environment |
否 |
pipeline顶层 / stage层级 |
定义全局/阶段私有环境变量 |
| options |
否 |
pipeline顶层 |
配置流水线全局参数（超时、重试、日志、权限） |
| triggers |
否 |
pipeline顶层 |
配置流水线自动触发规则（定时、代码提交触发） |
| parameters |
否 |
pipeline顶层 |
定义手动构建的入参变量 |
| when |
否 |
stage内部 |
阶段执行条件判断，满足条件才执行当前stage |
2.2 Agent 执行节点配置详解
agent用于指定流水线运行环境，可全局统一配置，也可单个阶段单独配置，优先级：阶段agent > 全局agent。
| Agent配置值 |
含义说明 |
代码示例 |
| any |
任意可用节点执行（默认常用） |
agent any |
| none |
全局不指定节点，每个stage单独配置agent |
agent none |
| label |
指定带对应标签的Agent节点执行 |
agent { label 'linux-build' } |
| docker |
基于指定Docker容器执行流水线 |
agent { docker 'maven:3.8-openjdk-8' } |
| dockerfile |
基于项目内Dockerfile构建容器并执行 |
agent { dockerfile true } |
| kubernetes |
在K8s集群中动态创建Pod执行任务 |
agent { kubernetes { yaml 'pod配置' } } |
2.3 Environment 环境变量配置
支持全局变量、阶段私有变量、密钥变量、动态变量，可直接在steps中 ${变量名} 引用。
| 变量类型 |
语法规则 |
代码示例 |
| 普通自定义变量 |
key-value直接赋值，全局所有阶段生效 |
environment { PROJECT_NAME 'demo-service' } |
| Jenkins内置变量 |
系统预设，直接引用，无需定义 |
echo 构建编号：${BUILD_NUMBER} |
| 密钥凭证变量 |
通过credentials()读取Jenkins凭证库，隐藏敏感信息 |
environment { PWD = credentials('db-pwd-id') } |
| 动态执行变量 |
通过sh脚本执行获取结果赋值变量 |
environment { VERSION = sh(script: 'git rev-parse --short HEAD', returnStdout: true) } |
| 阶段私有变量 |
定义在stage内部，仅当前阶段生效 |
stage('部署') { environment { ENV='prod' } } |
2.4 Options 流水线全局配置
| 配置项 |
功能说明 |
代码示例 |
| timeout |
设置流水线最大执行超时时间，超时自动终止 |
options { timeout(time: 30, unit: 'MINUTES') } |
| retry |
构建失败后自动重试次数 |
options { retry(2) } |
| timestamps |
控制台日志自动添加时间戳，方便问题排查 |
options { timestamps() } |
| buildDiscarder |
自动清理历史构建记录，节省磁盘空间 |
options { buildDiscarder(logRotator(numToKeepStr: '10')) } |
| disableConcurrentBuilds |
禁止流水线并发执行，避免部署冲突 |
options { disableConcurrentBuilds() } |
2.5 When 阶段条件判断
控制单个stage是否执行，满足条件才触发，支持分支、环境、参数、表达式等多种判断规则。
| 条件规则 |
适用场景 |
代码示例 |
| branch |
指定分支执行当前阶段 |
when { branch 'main' } |
| environment |
匹配环境变量值执行 |
when { environment name: 'ENV', value: 'prod' } |
| parameter |
匹配手动入参值执行 |
when { parameter name: 'DEPLOY', value: 'true' } |
| expression |
自定义Groovy表达式判断，灵活度最高 |
when { expression { return BUILD_NUMBER.toInteger() % 2 == 0 } } |
| allOf/anyOf |
多条件同时满足/任意满足 |
when { allOf { branch 'main'; environment name: 'ENV', value: 'prod' } } |
2.6 Post 后置处理规则
流水线/阶段执行完成后触发，支持按构建状态差异化执行，常用于日志归档、消息通知、资源清理。
| 触发条件 |
触发时机 |
典型用途 |
| always |
无论构建成功/失败/取消，始终执行 |
清理临时文件、统一日志归档 |
| success |
构建成功时触发 |
发送成功通知、推送制品仓库 |
| failure |
构建失败时触发 |
发送告警通知、失败日志汇总 |
| aborted |
构建手动取消时触发 |
取消任务告警、终止后续流程 |
| changed |
本次构建状态与上一次不同时触发 |
状态变更提醒（失败转成功、成功转失败） |
2.7 常用核心 Steps 步骤大全
steps块内的可执行操作，是流水线的核心执行逻辑，覆盖绝大多数CI/CD场景。
| 步骤名称 |
功能说明 |
代码示例 |
| sh |
执行Shell命令（Linux节点核心命令） |
sh 'mvn clean package -DskipTests' |
| bat |
执行Windows批处理命令 |
bat 'npm run build' |
| echo |
控制台打印日志、输出变量信息 |
echo "当前版本：${VERSION}" |
| git |
拉取代码仓库代码 |
git url: 'https://gitee.com/xxx/demo.git', branch: 'main' |
| archiveArtifacts |
归档构建产物，保存到Jenkins服务 |
archiveArtifacts artifacts: 'target/*.jar', fingerprint: true |
| deleteDir |
清空当前工作目录，清理缓存 |
deleteDir() |
| input |
人工确认卡点，用于生产部署审核 |
input message: '确认部署到生产环境？', ok: '确认部署' |
| script |
嵌套Groovy脚本，实现复杂逻辑（循环、判断、函数） |
script { if(ENV == 'prod') { println "生产部署" } } |
| sleep |
暂停构建，等待指定时间 |
sleep time: 5, unit: 'SECONDS' |
三、脚本式流水线核心语法精简
脚本式流水线基于原生Groovy，无固定结构，灵活度极高，适合复杂定制场景，以下为核心语法要点。
| 语法模块 |
核心说明 |
代码示例 |
| 基础结构 |
无需pipeline顶级块，直接node节点开始执行 |
node('linux') { ... } |
| 变量定义 |
使用def定义变量，支持字符串、数组、Map |
def project = 'demo'; def list = ['dev','prod'] |
| 流程控制 |
原生支持if/else、for、while、switch |
if(ENV == 'dev') { sh 'mvn clean install' } |
| 函数封装 |
支持自定义方法，复用流水线逻辑 |
def build(){ sh 'mvn package' } |
| 异常捕获 |
支持try-catch-finally捕获构建异常 |
try{ sh 'deploy' }catch(e){ println "部署失败" } |
四、Jenkins 核心内置变量汇总
| 内置变量名 |
变量含义 |
使用场景 |
| BUILD_NUMBER |
当前构建任务编号（自增数字） |
用于版本号拼接、日志标记 |
| BUILD_URL |
当前构建任务的访问链接 |
消息通知中携带构建地址 |
| WORKSPACE |
当前节点的工作目录路径 |
定位构建产物、临时文件路径 |
| GIT_BRANCH |
当前构建的Git分支名 |
根据分支差异化构建部署 |
| GIT_COMMIT |
当前代码最新commit哈希值 |
版本追溯、制品标记 |
| JOB_NAME |
当前流水线任务名称 |
多任务统一通知、统计 |
五、完整可运行声明式流水线模板
整合所有核心语法，适配常规Java项目CI/CD流程，可直接修改使用。
pipeline {
// 全局执行节点
agent any
// 全局环境变量
environment {
PROJECT = 'demo-service'
VERSION = sh(script: 'git rev-parse --short HEAD', returnStdout: true).trim()
}
// 全局流水线配置
options {
timeout(time: 30, unit: 'MINUTES')
retry(1)
timestamps()
disableConcurrentBuilds()
buildDiscarder(logRotator(numToKeepStr: '10'))
}
// 流水线核心阶段
stages {
stage('代码拉取') {
steps {
deleteDir() // 清空工作目录
git url: 'https://gitee.com/xxx/demo.git', branch: 'main'
echo "当前构建版本：${VERSION}"
}
}
stage('代码构建') {
steps {
sh 'mvn clean package -DskipTests'
}
}
stage('生产部署') {
when {
branch 'main' // 仅main分支执行部署
}
steps {
input message: '确认部署到生产环境？', ok: '确认部署'
sh 'sh deploy.sh'
}
}
}
// 后置处理
post {
always {
echo "流水线执行完毕，任务编号：${BUILD_NUMBER}"
}
success {
echo "构建部署成功！"
}
failure {
echo "构建部署失败，请排查日志！"
}
}
}
六、Jenkins 语法规范与避坑总结
| 规范类别 |
核心规则 & 避坑点 |
| 缩进规范 |
仅支持空格缩进，禁止Tab键，否则流水线直接报错 |
| 语法层级 |
声明式语法层级固定，stage内只能包含steps/when/environment，不能直接写脚本 |
| 变量引用 |
sh脚本中引用变量需注意引号，双引号可解析变量，单引号原样输出 |
| 并发构建 |
生产环境必须关闭并发构建，避免多任务部署冲突覆盖 |
| 敏感信息 |
密码、密钥必须通过credentials引用，禁止明文写入Jenkinsfile |
| 超时配置 |
所有流水线必须配置超时时间，防止任务卡死占用节点资源 |