如何在Jenkins Pipeline中展开不受控制字符串中的${ENV}变量？

这个问题我之前也碰到过，本质是因为参数化SCM里的模板变量在scm对象初始化阶段还没被解析成实际值——scm对象是在Pipeline加载的时候就创建的，而参数是运行时才传入的，所以直接取scm.branches[0].name拿到的还是占位符${REF}。给你几个靠谱的解决办法：

方法一：从checkout的返回结果中获取真实分支名 #

当你执行checkout scm时，Jenkins会返回一个包含版本控制信息的对象，其中就有已经解析好的分支名。我们可以捕获这个结果来获取真实值：

pipeline {
  agent any
  parameters {
    string(name: 'REF', defaultValue: 'main', description: 'Branch/Tag to build')
  }
  stages {
    stage('Checkout & Set Build Name') {
      steps {
        script {
          // 捕获checkout操作的返回结果
          def checkoutDetails = checkout scm
          // 从结果中提取真实分支名（GIT_BRANCH是Git SCM的标准键，其他SCM可能有不同键名）
          def actualBranch = checkoutDetails.GIT_BRANCH
          // 更新构建显示名称
          currentBuild.displayName = "${actualBranch} (#${BUILD_NUMBER})"
        }
      }
    }
    // 后续阶段...
  }
}

方法二：直接使用参数变量 #

既然${REF}对应的是你定义的参数，那直接调用params.REF就能拿到实际值，这是最直接的方式：

pipeline {
  agent any
  parameters {
    string(name: 'REF', defaultValue: 'main', description: 'Branch/Tag to build')
  }
  stages {
    stage('Set Build Name') {
      steps {
        script {
          // 直接使用参数值构建显示名称
          currentBuild.displayName = "${params.REF} (#${BUILD_NUMBER})"
        }
      }
    }
    stage('Checkout') {
      steps {
        checkout scm
      }
    }
    // 后续阶段...
  }
}

方法三：用env.expand()解析模板字符串 #

如果因为某些场景必须从scm.branches中获取值，可以用Jenkins内置的env.expand()方法来解析占位符，它能识别参数和环境变量：

pipeline {
  agent any
  parameters {
    string(name: 'REF', defaultValue: 'main', description: 'Branch/Tag to build')
  }
  stages {
    stage('Resolve Branch & Set Build Name') {
      steps {
        script {
          // 获取scm中的模板分支名
          def templateBranch = scm.branches[0].name
          // 展开占位符为实际参数值
          def actualBranch = env.expand(templateBranch)
          // 更新构建显示名称
          currentBuild.displayName = "${actualBranch} (#${BUILD_NUMBER})"
        }
      }
    }
    stage('Checkout') {
      steps {
        checkout scm
      }
    }
    // 后续阶段...
  }
}

为什么tm()会报错？ #

Token Macro插件的tm()方法是用来解析Jenkins专属的系统宏（比如${BUILD_URL}、${JOB_NAME}这类），而你的${REF}是自定义参数变量，不在它支持的宏列表里，所以会抛出“Unrecognized macro”错误。相比之下，env.expand()是Jenkins核心提供的方法，专门用于解析环境变量和参数占位符，更适合你的场景。

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