本文详解如何在 Jenkins Declarative Pipeline 中，利用 when 指令根据 choice 类型参数（如 'ME'、'FC'、'ME_and_FC'）动态控制 stage 的执行，避免语法错误并实现精准分支调度。
本文详解如何在 jenkins declarative pipeline 中，利用 `when` 指令根据 `choice` 类型参数（如 'me'、'fc'、'me_and_fc'）动态控制 stage 的执行，避免语法错误并实现精准分支调度。
在 Jenkins 声明式流水线（Declarative Pipeline）中，直接使用 if 语句包裹 stage 是非法的——这正是你遇到 not a valid syntax 错误的根本原因。Jenkins 不允许在 stages 块内自由嵌入 Groovy 控制流语句；正确方式是使用内置的 when 指令，它专为条件化执行 stage 而设计，语义清晰、语法安全、且与参数（params）天然兼容。
以下是一个完整、可运行的示例，支持三种构建类型：FC（仅执行 FC 相关 stage）、ME（仅执行 ME 并行子 stage）、ME_and_FC（两者均执行）：
pipeline {
parameters {
choice choices: ['ME', 'FC', 'ME_and_FC'], description: 'Select build type', name: 'Build_type'
}
agent {
node {
label 'Slave_APP_Train_32'
customWorkspace 'App_WS'
}
}
stages {
// ✅ FC-only stages — triggered only when Build_type is 'FC' or 'ME_and_FC'
stage('FC Stage 1') {
when { expression { params.Build_type == 'FC' || params.Build_type == 'ME_and_FC' } }
steps { echo "FC Stage 1: D6-EPS EXECUTED" }
}
stage('FC Stage 2') {
when { expression { params.Build_type == 'FC' || params.Build_type == 'ME_and_FC' } }
steps { echo "FC Stage 2: D6-EPS EXECUTED" }
}
stage('FC Stage 3') {
when { expression { params.Build_type == 'FC' || params.Build_type == 'ME_and_FC' } }
steps { echo "FC Stage 3: D6-EPS EXECUTED" }
}
// ✅ ME-only parallel stages — triggered only for 'ME' or 'ME_and_FC'
stage('ME Parallel Execution') {
when { expression { params.Build_type == 'ME' || params.Build_type == 'ME_and_FC' } }
steps {
script {
parallel(
'D6 SRA': {
node('Slave_APP_Train_32') {
ws('App_WS') {
echo "ME - D6 SRA: D6-EPS EXECUTED"
}
}
},
'D6 EPS': {
node('Slave_APP_Train_32') {
ws('App_WS') {
echo "ME - D6 EPS: D6-EPS EXECUTED"
}
}
},
'C3 EPS': {
node('Slave_APP_Train_32') {
ws('App_WS') {
echo "ME - C3 EPS: D6-EPS EXECUTED"
}
}
}
)
}
}
}
}
}
⚠️ 关键注意事项：
- when { expression { ... } } 中的闭包必须返回布尔值（true/false），不可省略 return（Groovy 中最后一行自动返回，但显式写 return 更清晰可靠）；
- ❌ 错误写法：if(${params.Build_type=='ME'}) —— ${...} 是字符串插值语法，不能用于 Groovy 表达式上下文，且 if 不是合法 stage 容器；
- ✅ 正确访问参数：始终用 params.Build_type（注意大小写），而非 env.BUILD_TYPE 或其他环境变量（除非显式赋值）；
- 若需复用逻辑，可将判断提取为函数（需置于 script 块或 options { skipDefaultCheckout(true) } 后的 post / environment 外部定义），但 when 内部不支持函数调用，建议保持表达式简洁；
- parallel 必须位于 steps 内，且推荐配合 script { parallel(...) } 使用，以确保语法兼容性（尤其在较新 Jenkins 版本中）。
通过 when 指令，你不仅能实现参数驱动的 stage 路由，还能获得 Jenkins UI 上清晰的 stage 状态标记（跳过阶段会显示“Skipped”），大幅提升流水线可维护性与可观测性。
