when 是干什么的
按分支、变更请求、环境或表达式决定阶段是否执行；配合 beforeAgent 与 beforeInput 控制条件求值时机，减少无谓节点占用与多余等待。条件是组合逻辑：用 not、allOf、anyOf 拼接多个判断。changeRequest 只在多分支流水线里有效，普通流水线用它判断不会命中，要留意生效范围。
基本信息
| 条件 | branch、changeRequest、environment、expression |
|---|---|
| 组合 | not、allOf、anyOf |
| 时机 | beforeAgent 提前在分配节点前求值 |
| 变更过滤 | changeset 按改动文件匹配 |
| 范围 | changeRequest 只在多分支流水线有效 |
典型使用场景
- 分支门禁：仅主分支阶段执行部署
- 变更请求检查：MR/PR 上跑额外校验
- 参数门禁：人工参数确认后才发布
- 改动过滤：按 changeset 只在相关文件变更时跑
- 排队优化：beforeAgent 提前求值省节点
- 环境区分：按环境变量分支执行
条件阶段
条件阶段
stage('deploy') {
when {
allOf {
branch 'main' # 仅主分支
expression { params.DEPLOY == true } # 且参数确认为真
}
}
steps { sh './deploy.sh' }
}条件读法
| 条件 | 判断什么 | 注意 |
|---|---|---|
| branch | 当前分支匹配 | 配合多分支流水线 |
| changeRequest | 变更请求 | 仅多分支流水线有效 |
| environment | 指定环境名 | 与环境变量区分 |
| expression | 任意布尔表达式 | 参数与变量判断 |
| changeset | 改动文件匹配 | 匹配范围要写准 |
beforeAgent 让条件在分配节点前求值：大集群里能省下可观排队时间。
组合逻辑写清楚：allOf 与 anyOf 混用时嵌套分明，避免语义走样。
条件不命中时阶段显示跳过而非失败：按跳过状态排查更准。
维护建议
- 跳过统计：定期看哪些阶段长期跳过，清理无用逻辑
- 参数联动：参数变更后下一次运行生效，条件随之重新求值
写否定条件先写肯定含义再取反，复杂判断的可读性更好。
changeset 的匹配范围要写清：范围过宽等于没过滤，过窄会漏跑。
正在运行的构建不受参数变更影响：调整后从下一次运行起生效。
嵌套层级控制：组合条件嵌套两层以上时改写表达式，可读性更好。
回归检查
- 升级核对：Jenkins 升级后抽样验证 when 行为是否符合预期