CI/CD / 系统课时
用 when 控制阶段执行条件
用 when 控制阶段执行条件
流水线中的某些阶段只应在特定分支、参数或运行条件下执行。Declarative Pipeline 的 when 可以把这些条件直接写在阶段上,让 Jenkins 在进入阶段前判断是否执行,从而避免为不同场景维护多份重复 Jenkinsfile。
学习目标
- 使用
when按分支和参数控制阶段执行 - 用
allOf、anyOf和not组合多个条件 - 知道什么时候使用
expression编写自定义判断
把执行条件放在阶段入口
when 写在 stage 内,用于描述该阶段的进入条件。条件不满足时,Jenkins 会跳过阶段,而不是把阶段内部步骤执行后再决定结果。
下面的 Jenkinsfile 让测试阶段始终运行,而部署阶段只有在 main 分支并且 DEPLOY=true 时执行。
pipeline {
agent any
parameters {
booleanParam(name: 'DEPLOY', defaultValue: false, description: '是否执行部署')
}
stages {
stage('Test') {
steps {
echo 'Run tests'
}
}
stage('Deploy') {
when {
allOf {
branch 'main'
expression { params.DEPLOY }
}
}
steps {
echo 'Deploy application'
}
}
}
}预期输出:在 Jenkins Multibranch Pipeline 的 main 分支上以 DEPLOY=true 运行时,示例中的关键输出为:
Run tests
Deploy application如果分支不是 main,或者 DEPLOY=false,Test 仍会输出 Run tests,但 Deploy 阶段不会执行其 echo。Jenkins 自身可能显示该阶段因条件不满足而被跳过,具体界面和附加日志取决于 Jenkins 版本及插件。
组合多个条件
单一条件可以直接写在 when 中;需要表达“同时满足”“任意满足”或“排除某条件”时,可以分别使用 allOf、anyOf 和 not。
allOf 适合生产部署这类严格入口,例如既要求正确分支,又要求显式开启部署。anyOf 适合多个合法入口中的任意一个成立即可执行。not 则用于明确排除某个条件。

这种声明方式比在 steps 中到处编写 Groovy if 更容易看出流水线结构:阅读阶段定义时就能知道它何时运行。
用 expression 处理自定义判断
内置条件无法表达业务规则时,可以使用 expression 返回布尔结果。例如参数值、环境变量或前面步骤保存的状态需要参与判断时,expression 更灵活。
不过能用 branch、environment 等声明式条件表达时,应优先使用它们。expression 中塞入过多脚本逻辑会让执行入口重新变得难以阅读和测试。
when 与步骤内 if 的边界
如果目标是决定整个阶段是否存在于本次执行路径中,优先使用 when。如果阶段必须进入,只是其中某个细小操作需要根据运行时结果变化,再考虑在 script 等合适上下文中使用 Groovy 条件判断。
把阶段级条件集中到 when 后,一份 Jenkinsfile 就能覆盖主分支部署、功能分支验证、参数化发布等不同路径,同时仍保留清晰的阶段结构。