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 创建构建目录、写入文件并检查结果。
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
'''
}
}
}
}预期输出
artifact-readyJenkins 日志还会包含命令回显、Stage 信息和 Workspace 路径,因此实际控制台内容会更多。这里真正需要验证的是 cat 输出了 artifact-ready,且 sh 最终以退出码 0 结束。
工作目录由 Workspace 决定
默认情况下,sh 在当前 Jenkins Workspace 中运行,而不是开发者电脑上的项目目录。脚本如果依赖相对路径,就必须确认仓库检出位置与目录结构。
需要进入子目录时,优先使用 Pipeline 的 dir 步骤明确切换作用域。例如项目的构建入口位于 backend 目录,可写成下面的片段示例;它依赖 Workspace 中已经存在 backend/build.sh。
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。
steps {
script {
int status = sh(
script: 'test -f build/status.txt',
returnStatus: true
)
if (status != 0) {
error 'build/status.txt does not exist'
}
}
}预期结果
当 build/status.txt 存在时,status 为 0,流水线继续执行;不存在时,status 为非 0,并由 error 主动终止当前流水线。这种写法适合需要根据退出码分支处理的检查。普通构建命令则没有必要捕获状态码后再手工判断,让 sh 按默认规则失败通常更直接。
获取命令输出
流水线有时需要把命令结果传给后续逻辑,而不只是打印到控制台。此时可以使用 returnStdout: true。返回字符串通常带末尾换行,因此常配合 trim()。
steps {
script {
String revision = sh(
script: 'git rev-parse --short HEAD',
returnStdout: true
).trim()
echo "revision=${revision}"
}
}预期输出
revision=<ID>其中 <ID> 是当前检出提交的短哈希,实际值随构建版本变化。需要注意,returnStdout 是为了取得标准输出;如果只是希望命令日志显示在 Jenkins 控制台,直接执行普通 sh 即可。
让 Shell 失败得足够明确
多行脚本中最危险的情况不是命令失败,而是失败没有传播到 Jenkins。对于简单脚本,可以使用 set -e 让未处理的失败命令终止脚本,set -u 则能及早暴露未定义变量。
不要为了让流水线变绿而随意在构建命令后添加 || true。这会把真实的编译、测试或部署错误转换成成功退出码,使 Jenkins 继续执行后续 Stage。只有某个失败明确属于允许状态时,才应捕获退出码并显式写出处理逻辑。
排查 Shell 步骤时,先确认当前 Workspace 和工作目录,再单独运行失败命令,最后检查退出码及所需文件。这样可以把“命令本身失败”和“Jenkins 执行上下文不正确”快速区分开。