Pipeline: Basic Steps
- catchError: 捕获错误并将构建结果设置为失败
- cleanWs: 自动清理空间
  - 清理文件
  - 使用其他删除程序
  - 其他参数
- deleteDir: 从工作区递归删除当前目录
- dir: 改变当前目录
- ws: 改变工作空间
- 工作空间中的 @tmp
- echo: 打印留言
- error: 错误信号
- fileExists: 验证文件是否存在于工作空间中
Declarative Syntax
Declarative Syntax
Scripted Syntax
Scripted Syntax
- isUnix: 检查是否在类 Unix 节点上运行
- mail：邮件
- pwd: 确定当前目录
- readFile: 从工作区读取文件
- retry: 重试执行最多 N 次
- sleep：睡觉
- stash: 存储一些文件以供稍后在构建中使用
- step：一般构建步骤
- timeout: 执行时间限制
tool：使用预定义工具安装中的工具
- unstable：将阶段结果设置为不稳定
- unstash: 恢复以前隐藏的文件
- waitUntil: 等待条件
- warnError: 捕获错误并将构建和阶段结果设置为不稳定
- withEnv: 设置环境变量
- wrap: 通用构建包装器
- writeFile: 将文件写入工作区
- sh: 执行 shell 命令
- 将 shell 的值赋值给变量
  - set -e 选项
  - set -x 选项
- archive: 存档工件
- getContext: 从内部 API 获取上下文对象
- unarchive: 将存档的工件复制到工作区
- withContext: 在块内使用来自内部 API 的上下文对象

Pipeline: Basic Steps

网站地址：Pipeline: Basic Steps

catchError: 捕获错误并将构建结果设置为失败

如果主体抛出异常，则将构建标记为失败，但仍然从该 catchError 步骤之后的语句继续执行流水线。抛出异常时步骤的行为可以配置为打印消息、设置非失败的构建结果、更改阶段结果或忽略用于中断构建的某些类型的异常。

此步骤在声明式管道中使用或与设置阶段结果或忽略构建中断的选项一起使用时最有用。否则，请考虑使用普通的 try-catch(-finally) 块。当使用最初为关注正在进行的构建结果的自由式项目定义的某些构建后操作（通知器）时，它也很有用。

node {catchError {sh 'might fail'}step([$class: 'Mailer', recipients: 'admin@somewhere'])
}

如果 shell 步骤失败，Pipeline 构建的状态将被设置为失败，以便后续的邮件步骤会看到此构建失败。对于邮件发件人，这意味着它将发送邮件。（如果此构建成功但之前的构建失败，它也可能发送邮件，依此类推。）即使在这种情况下，此步骤也可以替换为以下语法：

node {try {sh 'might fail'} catch (err) {echo "Caught: ${err}"currentBuild.result = 'FAILURE'}step([$class: 'Mailer', recipients: 'admin@somewhere'])
}

对于其他情况，可以使用普通的 try-catch(-finally) 块：

node {sh './set-up.sh'try {sh 'might fail'echo 'Succeeded!'} catch (err) {echo "Failed: ${err}"} finally {sh './tear-down.sh'}echo 'Printed whether above succeeded or failed.'
}
// …and the pipeline as a whole succeeds

有关背景，请参阅此文档。

buildResult: String（可选的）

如果捕获到错误，则整体构建结果将设置为此值。请注意，构建结果只会变得更糟，因此如果当前结果 UNSTABLE 或更糟，则无法将结果更改为 SUCCESS。使用 SUCCESS 或 null 来防止在捕获错误时设置构建结果。

catchInterruptions: boolean（可选的）

如果为 true，则用于中断 Pipelines 执行流程的某些类型的异常将被该步骤捕获和处理。如果为 false，这些类型的异常将被捕获并立即重新抛出。这些类型的异常示例包括通过 UI 手动中止构建时引发的异常以及 timeout 步骤引发的异常。默认为 true。

message: String（可选的）

如果捕获到错误，将记录到控制台的消息。如果指定了阶段结果，则消息也将与该结果相关联，并可能显示在可视化中。

stageResult: String（可选的）

如果捕获到错误，阶段结果将设置为此值。如果指定了消息，则该消息将与此结果相关联。使用 SUCCESS 或 null 来防止在捕获错误时设置阶段结果。

cleanWs: 自动清理空间

通常，当 pipeline 执行完成后，并不会自动清理空间。如果需要（通常需要）清理工作空间，则可以通过 Workspace Cleanup 插件实现。

post {always {cleanWs()}
}

清理文件

node {cleanWs patterns: [[pattern: '*.bak', type: 'INCLUDE'], [pattern: '*.tmp', type: 'INCLUDE']]
}

流水线提供了一个 cleanWs 步骤用于清理工作空间。默认情况下，无论构建结果如何，该步骤都会删除工作空间中的所有文件。如果清除失败，则会使构建失败。
默认情况下，将删除工作空间中的所有文件。但是，你可以添加文件模式以包含或排除删除文件类型。文件模式通过 patterns 参数，以及一个 pattern 和 type 的数组来定义（其中 patterns 是文件模式，type 是 include（包含）或 exclude（排除））。

使用其他删除程序

cleanWs 提供的另一个选项是，使用不同的删除程序。这是通过 externalDelete 参数完成的。此参数的依据是对备用删除应用程序的调用。采取以下形式：

<delete-program> [<delete-program-arguments>] %s

这里的 %s 被要删除的项替换，如其余的 cleanWs 命令选项解释的那样。环境变量可以通过 ${} 语法，合并到此字符串中。请注意，如果使用环境变量 <delete-program>，并且该环境变量设置为空字符串，则将使用节点上的默认删除程序。

在 Linux 系统上使用删除程序 shred 调用 externalDelete 选项可能如下所示：

cleanWs externalDelete: 'shred -uf %s'

其他参数

cleanWs 步骤的其余参数，都是针对各个要素的布尔值。请记住，步骤的默认形式只是 cleanWs，所以如果你不想要默认行为，只需要指定这些参数，则可以用到的参数如下：

cleanWhenAborted

默认为 true；如果设置为 false，则在中止构建状态时，该步骤不会清理工作空间。

cleanWhenFailure

默认为 true；如果设置为 false，则在构建状态失败时，该步骤不会清除工作空间。

cleanWhenNotBuilt

默认为 true；如果设置为 false，则在未构建项目时，该步骤将不会清理工作空间。

cleanWhenSuccess

默认为 true；如果设置为 false，则在构建状态成功时，该步骤不会清除工作空间。

cleanWhenUnstable

默认为 true；如果设置为 false，则在构建状态不稳定时，该步骤不会清除工作空间。

deleteDirs

默认为 false；如果设置为 true，也删除目录。请注意，如果提供了模式（如前面部分所述），则只会删除也与这些模式名称匹配的目录。

notFailBuild

默认为 true；如果设置为 false，则在清理步骤失败时，这将使整个构建失败。

deleteDir: 从工作区递归删除当前目录

递归删除当前目录及其内容。符号链接和交汇点将不被遵循，但将被删除。要删除工作区的特定目录，请将步骤包装 deleteDir 在一个 dir 步骤中。

dir('test') {deleteDir()
}

dir: 改变当前目录

更改当前目录。块内的任何步骤 dir 都将使用此目录作为当前目录，任何相对路径都将使用它作为基本路径。

path: String

工作区中用作新工作目录的目录的相对路径。

dir('/var/lib/test')

ws: 改变工作空间

更改当前的工作空间。

ws('myWorkspace')

ws 命令提供了锁定功能，这样多个任务就不能同时使用与工作空间相同的目录。而 dir 命令则不关心多个任务同时操作的场景。

工作空间中的 @tmp

有些时候工作空间会带着 @tmp 后缀，这是因为工作空间经常需要一些空间来放置非源码检出或编译区域的文件，比如：临时脚本、库文件等。

echo: 打印留言

message: String

要写入控制台输出的消息。

echo 'hello world!'

error: 错误信号

发出错误信号。如果您想有条件地中止程序的某些部分，这很有用。您也可以 throw new Exception()，但此步骤将避免打印堆栈跟踪。

message: String

捕获错误时将记录到控制台的消息。

error ("there's an error")

fileExists: 验证文件是否存在于工作空间中

检查当前节点上是否存在给定文件。返回 true | false。此步骤必须在 node 上下文中运行：

# Declarative Syntax
stage ('Check for existence of index.html') {agent any # 可以是顶级指令或阶段级指令steps {script {if (fileExists('src/main/rersources/index.html') {echo "File src/main/rersources/index.html found!"})}}
}

使用声明式语法，它必须在具有已定义代理的阶段中运行（例如：不同与 agent none）：

# Scripted Syntax
node {if (fileExists('src/main/rersources/index.html') {echo "File src/main/rersources/index.html found!"})
}

file: String

用于验证其存在的文件或目录的路径。
- 支持绝对路径和相对路径。使用相对路径时，它相对于当前工作目录（默认情况下：工作区）。
- Unix 和 Windows 路径都支持使用
分隔器：/
```
node('Linux') { if (fileExists('/usr/local/bin/jenkins.sh') { sh '/usr/local/bin/jenkins.sh' })
}
node('Windows') { if (fileExists ('C:/jenkins.exe') { bat 'C:/jenkins.exe' })
}
```
当使用带有反斜杠的 Windows 路径时 \ 分隔符，不要忘记转义它：

node('Windows') { if (fileExists('src\\main\\resources') { echo '找到目录资源。' }) }

isUnix: 检查是否在类 Unix 节点上运行

如果封闭 node 在类 Unix 系统（例如：Linux 或 Mac OS X）上运行，则返回 true，如果是 Windows，则返回 false。

script {def status=isUnixprint "${status}"
}

mail：邮件

发送电子邮件的简单步骤。

subject: String

电子邮件主题行。
body: String

电子邮件正文。
bcc: String（可选的）

密件抄送电子邮件地址列表。逗号分隔的电子邮件地址列表。
cc: String（可选的）

抄送电子邮件地址列表。逗号分隔的电子邮件地址列表。
charset: String（可选的）

电子邮件正文字符编码。默认为 UTF-8
from: String（可选的）

发件人电子邮件地址。默认为 Jenkins 实例全局配置的管理员地址。
mimeType: String（可选的）

电子邮件正文 MIME 类型。默认为 text/plain。
replyTo: String（可选的）

回复电子邮件地址。默认为 Jenkins 实例全局配置的管理员地址。
to: String（可选的）

到电子邮件地址列表。逗号分隔的电子邮件地址列表。

mail subject: 'Update', body: 'update all file', charset: 'UTF-8', mimeType: 'text', bcc: '', cc: 'zhangsan', from: 'wangwu', replyTo: '', to: 'lisi'

pwd: 确定当前目录

以字符串形式返回当前目录路径。

tmp: boolean（可选的）

如果选中，则返回与当前目录路径关联的临时目录，而不是目录路径本身。每个当前目录的返回值都不同。没有两个目录共享同一个临时目录。这是放置临时文件的合适位置，这些文件不应使源签出混乱；本地存储库或缓存；等默认为假。

script {def dir=pwdprint "dir"
}

readFile: 从工作区读取文件

从相对路径（当前目录中的根目录，通常是工作区）读取文件并将其内容作为纯字符串返回。

file: String

工作区中要读取的文件的相对（/分隔）路径。
encoding: String（可选的）

读取文件时使用的编码。如果留空，将使用平台默认编码。通过将 “Base64” 指定为编码，可以将二进制文件读入 Base64 编码的字符串。

fileContents = readFile(file: "/etc/passwd", encoding: "UTF-8")
echo "$fileContents"

retry: 重试执行最多 N 次

如果在其主体执行期间发生任何异常，请重试该块（最多 N 次）。如果在最后一次尝试中发生异常，那么它将导致构建中止（除非它被捕获并以某种方式处理）。构建的用户中止不会被捕获。

count: int
conditions（可选的）
应该重试块的条件。如果没有匹配，则该块将失败。如果没有指定条件，除非用户中止，否则将始终重试该块。

对象的嵌套选择数组/列表
- agent
- kubernetesAgent
- nonresumable

steps {retry(20) {script {sh script: 'curl http://example', returnStatus: true}}
}

sleep：睡觉

只需暂停管道构建，直到给定的时间到期。相当于（在 Unix 上）sh 'sleep …'。可用于在 parallel 的一个分支进行时暂停另一个分支。

time: int

步骤将休眠的时间长度。
unit（可选的）

时间参数的单位。如果未指定，则默认为 “SECONDS”。
- 值：NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS

sleep(120) // 120 秒
sleep(time:'2', unit:"MINUTES") // 2 分钟

stash: 存储一些文件以供稍后在构建中使用

保存一组文件，供以后在同一管道运行中的任何节点/工作区上使用。默认情况下，隐藏的文件在管道运行结束时被丢弃。其他插件可能会改变这种行为，以将存储库保存更长时间。例如：声明性管道包含一个 preserveStaches() 选项，允许在重新启动运行时保留和使用运行中的数据。

在其他运行、其他管道或其他作业中，一个管道中的作业不可用。如果您想将工件持久化以在单个运行之外使用，请考虑改用 archiveArtifacts。请注意，stash 和 unstash 步骤是为小文件设计的。对于大型数据传输，请使用 External Workspace Manager 插件，或使用外部存储库管理器，例如：Nexus 或 Artifactory。这是因为隐藏的文件是在压缩的 TAR 中归档的，对于大型文件，这需要大量的主资源，尤其是 CPU 时间。没有硬存储大小限制，但在 5-100 MB 之间，您可能应该考虑其他选择。

name: String

要存储的一组文件唯一标识名称。
allowEmpty: boolean（可选的）

即使不包含文件，也创建存储。如果 false（默认），当存储不包含文件时会引发错误。
excludes: String（可选的）

可选的一组 Ant 样式排除模式。
使用逗号分隔列表添加多个表达式。
如果为空，则不会排除任何文件。
includes: String（可选的）

可选的一组 Ant 样式包含模式。
使用逗号分隔列表添加多个表达式。
如果为空，则视为 **：所有文件。
当前工作目录是保存文件的基本目录，稍后将恢复到相同的相对位置，因此如果您想使用子目录，请将其包装在 dir。
useDefaultExcludes: boolean（可选的）

如果选中，则使用 Ant 的默认排除项 - 请参阅此处以获取列表。默认为真。

stash includes: '**', name: 'test'

step：一般构建步骤

这是一个特殊的步骤，允许调用构建器或构建后操作（如：在自由式或类似项目中），通常是 “构建步骤”。只需从下拉列表中选择要调用的构建步骤并根据需要进行配置。

请注意，列表中只会显示与管道兼容的步骤。

要使用此步骤，您需要指定一个委托类，例如：step([$class: 'A3Builder'])。

timeout: 执行时间限制

以确定的超时限制执行块内的代码。如果达到时间限制，则会引发异常（org.jenkinsci.plugins.workflow.steps.FlowInterruptedException），从而导致构建中止（除非它被捕获并以某种方式处理）。

time: int

此步骤在取消嵌套块之前将等待的时间长度。
activity: boolean（可选的）

此块的日志中没有活动后超时，而不是绝对持续时间。默认为 false。
unit（可选的）

时间参数的单位。如果未指定，则默认为 “MINUTES”。
- 值：NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS

timeout(1)timeout(unit: 'SECONDS', time: 5)

tool：使用预定义工具安装中的工具

将工具安装绑定到变量（返回工具主目录）。此处仅提供已配置的工具 Configure System。如果原始工具安装程序具有自动配置功能，则将根据需要安装该工具。

name: String

工具的名称。工具名称必须在 Jenkins 中的 Manage Jenkins → Global Tool Configuration 下预先配置。
type: String（可选的）

从可用的内置工具提供程序中选择类型。

steps {script{def t = tool name: 'docker', type: 'org.jenkinsci.plugins.docker.commons.tiils.ockerTool'echo "${t}" //打印 /var/lib/docker}
}

unstable：将阶段结果设置为不稳定

将消息打印到日志并将整体 构建结果 和 阶段结果 设置为 UNSTABLE。该消息还将与阶段结果相关联，并可能显示在可视化中。

message: String

将记录到控制台的消息。该消息还将与阶段结果相关联，并可能显示在可视化中。

unstash: 恢复以前隐藏的文件

恢复以前存储在当前工作区中的一组文件。

将一组先前编辑的文件 stash 恢复到当前工作区。

name: String

先前保存的存储的名称。

unstash('test')unstash 'test'

waitUntil: 等待条件

反复运行，直到它返回 true。如果返回 false，请稍等片刻，然后重试。（随后的失败会减慢尝试之间的延迟，最长可达 15 秒。）重试次数没有限制，但如果主体抛出错误，则会立即抛出。

waitUntil 步骤最好与 timeout 步骤共同使用，避免死循环

initialRecurrencePeriod: long（可选的）

设置重试之间的初始等待时间（以毫秒为单位）。默认为 250 毫秒。
每次失败都会将尝试之间的延迟减慢至最多 15 秒。
quiet: boolean（可选的）

如果为 true，则每次检查条件时该步骤都不会记录消息。默认为 fail。

timeout(50) {waitUntil {script {def r = sh script: 'curl http://exmaple', returnStatus: truereturn (r == 0)}}
}

warnError: 捕获错误并将构建和阶段结果设置为不稳定

执行它的主体，如果抛出异常，将整体构建结果和阶段结果设置为 UNSTABLE，将指定消息和抛出的异常打印到构建日志中，并将阶段结果与消息关联，以便显示可视化。

相当于 catchError(message: message, buildResult: 'UNSTABLE', stageResult: 'UNSTABLE')。

message: String

如果捕获到错误，将记录到控制台的消息。该消息还将与阶段结果相关联，并可能显示在可视化中。
catchInterruptions: boolean（可选的）

如果为 true，则用于中断 Pipelines 执行流程的某些类型的异常将被该步骤捕获和处理。如果为 false，这些类型的异常将被捕获并立即重新抛出。这些类型的异常示例包括通过 UI 手动中止构建时引发的异常以及 timeout 步骤引发的异常。默认为 true。

withEnv: 设置环境变量

在块中设置一个或多个环境变量。环境变量的名称不区分大小写但保留大小写，即设置 Foo 将更改 FOO 的值，如果它已经存在。环境变量可用于该范围内产生的任何外部进程。例如：

多个环境变量用 , 号隔开

node { withEnv(['MYTOOL_HOME=/usr/local/mytool']) { sh '$MYTOOL_HOME/bin/start' }
}node { withEnv(['MYTOOL_HOME=/usr/local/mytool', 'aaa=bbb']) { sh '$MYTOOL_HOME/bin/start' }
}

请注意，这里我们在 Groovy 中使用单引号，因此变量扩展是由 Bourne shell 完成的，而不是 Jenkins。）

env 有关环境变量的更多信息，请参阅单例文档。

overrides: Array / List of String

要设置的环境变量列表，每个变量都以其他形式定义 VARIABLE=value 或 VARIABLE= 取消设置变量。您也可以使用 PATH+WHATEVER=/something 添加 /something 到 $PATH。

wrap: 通用构建包装器

这是一个允许调用构建包装器的特殊步骤（在自由式或类似项目中也称为 “环境配置”）。只需从下拉列表中选择要使用的包装器并根据需要进行配置。包装块内的所有内容都在其作用下。

请注意，列表中只会显示与管道兼容的包装器。

要使用此步骤，您需要指定一个委托类，例如：wrap([$class: 'AnsiColorBuildWrapper'])。

writeFile: 将文件写入工作区

将给定的内容写入当前目录中的命名文件。

file: String

工作区中文件的相对路径。
text: String

要写入文件的数据。
encoding: String（可选的）

文件的目标编码。如果留空，将使用平台默认编码。如果文本是 Base64 编码的字符串，则可以通过指定 “Base64” 作为编码将解码后的二进制数据写入文件。

script {writeFile(file: "/etc/pass", text: "xxxx", encoding: "UTF-8")
}或script {def filename = "test.txt"def text_txt = """aaabbbccc""".stripIndent()writeFile file: filename, text: text_txt
}

sh: 执行 shell 命令

执行 shell 的命令

script

要执行的 shell 脚本，可以是多行脚本
encoding

脚本执行后输出日志的编码，默认值为脚本运行所在系统的编码。
returnStatus

布尔类型，默认脚本返回的是状态码，如果是一个非零的状态码，则会引发 pipeline 执行失败。如果 returnStatus 参数为 true，则不论状态码是什么，pipeline 的执行都不会受影响。
returnStdout

布尔类型，如果为 true，则任务的标准输出将作为步骤的返回值，而不是打印到构建日志中（如果有错误，则依然会打印到日志中）。

returnStatus 和 returnStdout 参数一般不会同时使用，因为返回值只有一个。如果同时使用，只有 returnStatus 参数生效

sh "ls"sh script: '/root/test.sh', returnStdout: true

将 shell 的值赋值给变量

node {def tag = sh(script: "git describe --tags --always", returnStdout: true).trim()
}

script（脚本）

要执行的操作，表示为字符串。这是默认参数，因此，如果这是你正使用的唯一参数，则不必指定脚本。可以使用多行脚本，但需要你将它们用三重引号括起来。
encoding（编码）

输出的编码，表示为字符串。如果你需要使用 UTF-8 默认值以外的其他内容，则只需设置此项即可。
returnStdout（返回标准输出）

返回一个布尔值。如果将其设置为 false（默认值），则只会将 stdout 打印到控制台日志中。如果将其设置为 true，则 stdout 将作为字符串从步骤返回。（提示：如果需要，你可以使用 trim() 去除行尾换行符。）
returnStatus（返回状态）

一个布尔值。如果将此值设置为 false（默认值），则非零状态代码将导致步骤失败并抛出异常。如果将其设置为 true，则状态代码将是步骤中的返回代码。你可以获取该返回代码并进行检查，之后采取相应的措施。

请注意，每次调用 shell 步骤的设置时，只能对 returnStdout 或 returnStatus 进行二选一。另外，对于 returnStdout 选项，如果有任何 stderr 输出，它仍将转到控制台日志。

set -e 选项

默认情况下，如果脚本中存在错误，shell 将不会停止。它会尝试执行所有的行。但是，这通常不是你所需要的（特别是如果你使用 shell 命令作为流水线脚本的一部分的时候）。

因此，Jenkins 中的 sh 步骤自动包含一个 set -e 选项。如果运行到某一行时遇到错误，这将使 shell 停止执行，不会运行其余的代码。

如果出于某种原因，你更希望让 Jenkins 执行脚本中的所有行，而不管其中一行是否有问题，就可以在开始时添加 set +e 语句，用于关闭 “遇到第一个错误行后，脚本即停止执行” 功能。

set -x 选项

在运行 shell 操作的输出中，每个 shell 命令在运行时显示出前面带有 + 号。这是由于 Jenkins 自动设置了另一个选项 -x。-x 选项使 sh 步骤在执行它时逐个显示被调用的操作系统内置命令。如果你想关闭它，可以将 set +x 选项添加到 sh 步骤。

archive: 存档工件

存档构建输出工件供以后使用。从 Jenkins 2.x 开始，此步骤已被弃用，取而代之的是更可配置的 archiveArtifacts。

includes: String

包括与此 Ant 样式模式匹配的工件。使用逗号分隔列表添加多个表达式。
excludes: String（可选的）

排除与此 Ant 样式模式匹配的工件。
使用逗号分隔的列表添加多个表达式。

archive includes: 'aaa.txt, bbb.txt'

getContext: 从内部 API 获取上下文对象

在 StepContext.get 中获取上下文对象。参见 withContext。接受一个 type 的参数。例子：

getContext hudson.FilePath

用于可操作内部 Jenkins API 的受信任代码，例如：全局库。

type
- 类型：java.lang.Class<?>

unarchive: 将存档的工件复制到工作区

mapping（可选的）
- 类型：java.util.Map<java.lang.String, java.lang.String>

withContext: 在块内使用来自内部 API 的上下文对象

将块包装在上下文对象中，如：BodyInvoker.withContext; 参看 getContext。接受一个 context 参数加上一个块。例子：

withContext(new MyConsoleLogFilter()) {sh 'process'
}

在 ConsoleLogFilter、LauncherDecorator 和 EnvironmentExpander 的情况下，自动将其参数与上下文对象合并。