如何在 Jenkins 流水线中执行 Shell 脚本传递构建参数？

在 Jenkins 流水线中，通过 Groovy 双引号字符串插值将参数传递给 Shell 脚本是最推荐的做法，适用于 Declarative 和 Scripted Pipeline 场景，风险边界在于未转义的特殊字符可能导致 Shell 注入。

先说结论：使用 Groovy 双引号包裹 sh 步骤并直接引用 params 对象可安全传递参数

适合：需要在构建时动态指定版本、环境或配置项的流水线任务
先准备：在 Jenkinsfile 顶层 parameters 块定义参数类型和默认值
验收：在 Shell 脚本中 echo 参数值并在控制台确认内容符合预期

命令速用版

pipeline {
    parameters {
        string(name: 'VERSION', defaultValue: '1.0', description: '构建版本')
    }
    stages {
        stage('Build') {
            steps {
                sh "echo Building version ${params.VERSION}"
            }
        }
    }
}

为什么会这样

Jenkins Pipeline 基于 Groovy 语言，sh 步骤中的双引号字符串会先由 Groovy 引擎进行变量替换，然后再交给 Shell 执行。

如果使用单引号，Groovy 不会解析变量，Shell 也读取不到 Jenkins 环境变量，导致参数传递失败。理解 Groovy 插值与 Shell 变量展开的执行顺序是配置成功的关键。

分步处理

步骤 1：定义构建参数

在 Jenkinsfile 的 parameters 块中声明参数，支持 string、choice、booleanParam 等类型。

parameters {
    string(name: 'DEPLOY_ENV', defaultValue: 'test')
}

步骤 2：在 Groovy 中引用参数

使用 ${params.PARAM_NAME} 语法在双引号字符串中引用参数，不要直接使用 $PARAM_NAME。

sh "deploy.sh `--env` ${params.DEPLOY_ENV}"

步骤 3：处理特殊字符

如果参数包含空格或特殊符号，建议在 Shell 侧用引号包裹变量，防止单词拆分。

sh "echo \"${params.USER_INPUT}\""

怎么验证是否生效

查看 Jenkins 构建任务的 Console Output，搜索 echo 输出的参数值。

确认控制台显示的值与构建时输入的值一致，且没有多余的引号或转义字符错误。

常见坑

单引号陷阱：sh 'echo ${params.VERSION}' 不会输出参数值，因为单引号禁止 Groovy 插值。

Shell 注入风险：如果参数允许用户自由输入，直接拼接可能引发命令注入，建议对输入内容做白名单校验。

环境变量冲突：params 对象优先于 env 对象，避免定义同名的全局环境变量。

常见问题

params 和 env 获取参数有什么区别？

params 用于访问构建时定义的 parameters 块参数，env 用于访问系统环境变量或 environment 块定义的变量。

如何传递多个参数给 Shell 脚本？

在 sh 步骤中依次列出多个 ${params.NAME} 插值，Shell 脚本通过 $1 $2 或命名参数接收。

参数包含空格会导致脚本出错吗？

会，建议在 sh 步骤中给插值变量加上双引号，确保 Shell 将其视为单个参数。

参考来源

Jenkins Official Documentation, Pipeline Syntax, https://www.jenkins.io/doc/book/pipeline/syntax/
Jenkins Official Documentation, Using parameters, https://www.jenkins.io/doc/book/pipeline/syntax/#parameters