CI/CD / 系统课时

在 steps 中执行 Shell 命令

在 steps 中执行 Shell 命令

Jenkins 流水线最终要把编译、测试和打包落到具体命令上。使用 sh 可以在 Linux 或类 Unix Agent 中执行 Shell 命令,但要同时处理工作目录、退出码和输出,否则脚本在本地成功,进入流水线后仍可能失败。

学习目标

  • 在 steps 中正确使用 sh 执行构建脚本和 Linux 命令
  • 理解 Jenkins Workspace、dir 与命令工作目录的关系
  • 正确利用退出码和标准输出控制流水线行为

从 steps 执行命令

Declarative Pipeline 的 steps 描述某个 Stage 真正执行的动作。在 Linux Agent 上,最常见的动作之一就是调用 sh。下面的 Jenkinsfile 创建构建目录、写入文件并检查结果。

groovy
pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh '''
                    set -eu
                    mkdir -p build
                    printf '%s\n' 'artifact-ready' > build/status.txt
                    cat build/status.txt
                '''
            }
        }
    }
}

预期输出

text
artifact-ready

Jenkins 日志还会包含命令回显、Stage 信息和 Workspace 路径,因此实际控制台内容会更多。这里真正需要验证的是 cat 输出了 artifact-ready,且 sh 最终以退出码 0 结束。

工作目录由 Workspace 决定

默认情况下,sh 在当前 Jenkins Workspace 中运行,而不是开发者电脑上的项目目录。脚本如果依赖相对路径,就必须确认仓库检出位置与目录结构。

需要进入子目录时,优先使用 Pipeline 的 dir 步骤明确切换作用域。例如项目的构建入口位于 backend 目录,可写成下面的片段示例;它依赖 Workspace 中已经存在 backend/build.sh。

groovy
steps {
    dir('backend') {
        sh './build.sh'
    }
}

生效行为:进入 dir 作用域后,./build.sh 相对于 Workspace 下的 backend 解析;离开作用域后,后续步骤恢复原来的工作目录。验证时可临时执行 pwd 和 ls,确认实际路径及文件是否存在。

不要把开发机上的绝对路径写进 Jenkinsfile。Agent 可能更换节点、容器或 Workspace,固定的 /home/<ID>/project 很容易失效。

退出码决定步骤是否成功

Shell 命令通常以 0 表示成功,以非 0 表示失败。默认的 sh 会把非 0 退出码转化为 Pipeline 步骤失败,因此构建工具、测试命令和部署脚本可以自然阻断后续流程。

如果非 0 是业务上允许检查的状态,可以使用 returnStatus: true 获取退出码,而不是立即让步骤失败。下面是片段示例,依赖当前 Workspace 中可能存在 build/status.txt。

groovy
steps {
    script {
        int status = sh(
            script: 'test -f build/status.txt',
            returnStatus: true
        )
        if (status != 0) {
            error 'build/status.txt does not exist'
        }
    }
}

预期结果

text
当 build/status.txt 存在时,status 为 0,流水线继续执行;不存在时,status 为非 0,并由 error 主动终止当前流水线。

这种写法适合需要根据退出码分支处理的检查。普通构建命令则没有必要捕获状态码后再手工判断,让 sh 按默认规则失败通常更直接。

获取命令输出

流水线有时需要把命令结果传给后续逻辑,而不只是打印到控制台。此时可以使用 returnStdout: true。返回字符串通常带末尾换行,因此常配合 trim()。

groovy
steps {
    script {
        String revision = sh(
            script: 'git rev-parse --short HEAD',
            returnStdout: true
        ).trim()
        echo "revision=${revision}"
    }
}

预期输出

text
revision=<ID>

其中 <ID> 是当前检出提交的短哈希,实际值随构建版本变化。需要注意,returnStdout 是为了取得标准输出;如果只是希望命令日志显示在 Jenkins 控制台,直接执行普通 sh 即可。

让 Shell 失败得足够明确

多行脚本中最危险的情况不是命令失败,而是失败没有传播到 Jenkins。对于简单脚本,可以使用 set -e 让未处理的失败命令终止脚本,set -u 则能及早暴露未定义变量。

不要为了让流水线变绿而随意在构建命令后添加 || true。这会把真实的编译、测试或部署错误转换成成功退出码,使 Jenkins 继续执行后续 Stage。只有某个失败明确属于允许状态时,才应捕获退出码并显式写出处理逻辑。

排查 Shell 步骤时,先确认当前 Workspace 和工作目录,再单独运行失败命令,最后检查退出码及所需文件。这样可以把“命令本身失败”和“Jenkins 执行上下文不正确”快速区分开。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

在 steps 中执行 Shell 命令

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通