能否在Jenkinsfile的自定义函数内使用when语句？

核心结论 #

自定义函数内部不能直接使用when语句，因为when是Jenkins Declarative Pipeline的专属语法，仅允许嵌套在stage块内部，不属于可在普通自定义函数中调用的步骤命令。

问题原因分析 #

1. if与when的显示差异：

   • if属于Scripted Pipeline的逻辑判断，即使分支未执行，整个stage仍会被标记为执行完成（绿色状态），只是内部步骤跳过，Blue Ocean不会展示“跳过”的白色状态。
   • when是Declarative Pipeline的阶段控制语法，当条件不满足时，整个stage会被直接标记为跳过（白色状态），这正是你需要的效果。

2. 函数内无法使用when的本质：
   Jenkins的Declarative语法有严格的结构约束，when必须直接隶属于stage节点，不能放置在自定义函数、普通步骤等非stage结构中，否则会触发语法校验错误。

可行解决方案 #

要实现“指定服务器才执行、Blue Ocean显示跳过状态”的需求，需将when配置在parallel的每个子stage上，而非封装到自定义函数内。示例代码如下：

pipeline {
  agent any
  parameters {
    string(name: 'TARGET_SERVERS', defaultValue: '', description: '指定要更新的服务器，用逗号分隔')
  }
  stages {
    stage('Parallel Deploy') {
      parallel {
        // 遍历预配置服务器数组，为每个服务器生成独立子stage
        for (env in preconfiguredServers) {
          stage("Deploy to ${env}") {
            // 将判断逻辑放在when中
            when {
              expression { 
                params.TARGET_SERVERS.split(',').contains(env) 
              }
            }
            steps {
              script {
                // 调用原有自定义部署函数
                deployEnvironment(env)
              }
            }
          }
        }
      }
    }
  }
}

// 保留原自定义函数的部署逻辑
def deployEnvironment(env) {
  defineEnvironment()
  defineAgent('build')
  deploy(env)
}

关键说明 #

• 每个子stage单独配置when，条件不满足时Blue Ocean会显示白色跳过状态，符合预期展示效果。
• 自定义函数仅负责封装部署逻辑，将阶段控制的when留在Declarative的stage结构中，避免语法冲突。

内容的提问来源于stack exchange，提问作者Banns