配置构建步骤

build step（构建步骤）是 CI/CD 工作流中的最小单位。用于定义作为整体执行的一组特定操作。构建步骤隶属于构建配置和管道作业。

构建配置与管道中的构建步骤

TeamCity 提供多种构建步骤，适用于特定的构建工具，例如 .NET、 Maven、 NAnt 或 Xcode。

完整的步骤集目前适用于构建配置。管道在 2025.07 版本中引入，当前仅支持有限的子集。不过，您可以使用脚本步骤构建任意项目类型，因为此步骤可使用代理机中安装的任意工具运行命令。

通过 TeamCity UI 添加步骤

构建配置

打开配置设置并导航到 构建步骤 设置选项卡。
点击添加构建步骤手动选择构建步骤，或点击自动检测构建步骤，让 TeamCity 扫描由 VCS 根指向的远程仓库并推荐适当的步骤。
扫描仓库时，TeamCity 会在源树的最上层两级目录中查找项目文件，并根据文件扩展名识别项目类型。例如：
- PowerShell： .ps1
- .NET： project.json， .proj， .csproj， .vbproj， .sln
如果建议的步骤已添加到配置中，TeamCity 将在推荐列表中跳过该步骤。

新建构建步骤页面包含两列：

默认步骤 — 由 JetBrains 预定义。
配方（原称为元运行器）— 由 TeamCity 社区或您的团队创建的自定义 XML 或 YAML 步骤。

是否能访问 JetBrains Marketplace 中的公共配方取决于您的项目设置。请参阅以下文章以了解更多信息：使用配方.

Pipelines

打开作业设置，然后在侧边设置面板中滚动到步数部分。
点击任意图块以添加相应的构建步骤。

在代码中添加步骤

TeamCity 支持以配置即代码形式编写 Kotlin DSL 和 YAML （当前仅适用于管道）。

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.maven
import jetbrains.buildServer.configs.kotlin.buildSteps.script

object SampleConfig: BuildType({
    name = "Sample two-step configuration"
    steps {
        script {
            name = "Step 1"
            id = "simpleRunner"
            scriptContent = """echo "Hello world""""
        }
        maven {
            name = "Step 2"
            id = "Step_2"
            goals = "clean package"
            jdkHome = "%env.JDK_21_0_ARM64%"
            mavenVersion = custom {
                path = "%teamcity.tool.maven.3.8.6%"
            }
        }
    }
})

    

Job1:
    name: Sample two-step job
    steps:
      - type: script
        name: Step 1
        script-content: echo "Hello world"
      - type: maven
        name: Step 2
        pom-location: pom.xml
        goals: clean package
        jdk-home: '%env.JDK_21_0_ARM64%'
        maven-version:
          bundled_3_8: {}

    

步骤执行条件

构建步骤按从上到下的顺序运行，顺序与 UI 或配置代码中的显示一致。默认情况下，TeamCity 会执行所有步骤，直到某个步骤失败。如果某个步骤失败，构建将标记为失败并跳过其后的所有步骤。默认情况下，TeamCity 会执行所有步骤，直到某个步骤失败。如果某个步骤失败，构建将标记为失败并跳过其后的所有步骤。

您可以在构建配置中设置自定义执行策略，以覆盖此默认行为并定义步骤运行条件。

执行条件包括两个部分：

从相应下拉菜单中选择的常规规则。
通过添加条件菜单添加的可选附加条件。

常规执行规则

仅当构建状态为成功时 — 在开始步骤之前，构建代理会从服务器请求构建状态，如果状态为“失败”，则跳过该步骤。这考虑了服务器处理的故障条件，如测试失败或度量改变时的故障。请注意，由于部分错误条件是在服务器上异步处理的（TW-17015 ），所以情况可能并不准确。
仅当构建状态为失败时 — 与上述相同，但如果构建状态为“成功”，代理会跳过该步骤。此条件适用于执行回滚或清理操作。
如果所有先前步骤均成功完成 — 如果代理上的所有前序步骤成功，则会执行该步骤，而不检查服务器报告的构建状态。
即使某些先前步骤失败 — 无论前序步骤结果或构建状态如何，均会执行该步骤。
Always, even if build stop command was issued — 即使构建已取消，也确保执行该步骤。例如，如果两个步骤使用此设置，并且构建在第一个步骤期间被停止，那么第二个步骤仍会执行。再次发出停止命令将完全终止该构建。

其他条件

您可以使用自定义条件进一步限定执行行为。例如，可以在个人构建或非默认分支中跳过步骤，或者通过检查 teamcity.agent.jvm.os.name 参数值执行操作系统特定步骤。

有关更多信息，请参阅以下主题：构建步骤执行条件。

引导步骤

在构建触发后，构建代理检出源文件之前，会执行一个引导步骤。这允许您添加一个运行器（通常是命令行（脚本）运行器），该运行器执行初始设置并确保后续步骤按预期运行。

要启用 bootstrap steps，首先将 teamcity.internal.bootstrap.steps.enabled=true 条目添加到 TeamCity 内部属性或单个项目（作为该项目的配置参数）。此设置使您能够执行以下操作：

在步骤设置中启用在引导期间运行选项。
在配置的构建步骤页面上，点击重排构建步骤，然后将所需步骤拖动到“准备阶段”块之前。

您可以创建一个带有 bootstrap 步骤的构建配置，并将此配置变成一个 template。这种模板允许您在实际构建过程开始之前快速创建更多执行所需前提操作的配置。

Recipes 被视为单个步骤，因此无法分为在签出之前和之后执行的部分。

要在 Kotlin DSL 中将普通步骤变为 bootstrap 步骤，请添加 teamcity.step.phase 参数并将其值设置为“bootstrap”。

object MyConfig : BuildType({
  // ...
  steps {
    script {
      name = "Disk prep"
      id = "simpleRunner"
      scriptContent = "echo 'Initial setup'"
      param("teamcity.step.phase", "bootstrap") // Bootstrap step
    }
    // Regular steps
  }
  // ...
})

  

无代理构建步骤

无代理构建步骤是可以在外部软件中运行且无需附加 build agent 的步骤。

通常，一个正在运行的构建会占用一个构建代理，直到完全结束，即使其最后的步骤是在 TeamCity 之外执行的。然而，如果构建不需要其代理进行一些剩余步骤，它可以从此代理分离。代理一旦可用，即可立即分配给另一个构建。

这种方法可以节省代理的工作时间，并且对于使用第三方工具完成构建的配置来说是最优的：例如，运行众多测试或部署项目。这样的构建可以在 TeamCity 外部完成；TeamCity 服务器将直接检测其状态报告，无需通过代理作为中介。

让我们考虑一个包含三个步骤的示例构建：编译，测试和部署。即使部署步骤实际上是由外部软件执行的，所有这些都由代理处理。代理仅在轮询外部软件并将构建状态报告给 TeamCity 服务器。

在无代理的方法中，代理无需处理最终的部署步骤，并且可以运行队列中的其他构建。 TeamCity 服务器将直接从外部工具中捕获以下报告。

另请参阅：将构建与 Agent 分离

步骤状态参数

TeamCity 提供了报告给定 ID 步骤状态的 teamcity.build.step.status.<步骤_ID> 参数。例如，这些参数可用于构建更复杂的执行条件。

步骤 ID 显示在其名称下方，只有在创建它们时才可以编辑。

teamcity.build.step.status.<步骤_ID> 参数的可用值为：

成功 — 当一个步骤没有错误地完成时。
失败 — 当一个步骤失败时。即使所有构建问题都被静音，也会报告此状态。
已取消 — 当该步骤运行时，构建被取消。

参数 teamcity.build.step.status.<步骤_ID> 只有在其对应的步骤完成后才会出现，而不是在构建开始的瞬间就可用。这意味着既正在运行的步骤，也被跳过的步骤都无法获得其 teamcity.build.step.status.<步骤_ID> 参数。

您可以在构建结果页面的参数选项卡中检查所有步骤的状态...

...或通过 TeamCity REST API。

http://<SERVER_URL>/app/rest/builds/<BUILD_ID>/resulting-properties

附加信息

您可以从原始构建配置设置页面将构建步骤复制从一个构建配置到另一个。
您可以根据需要调整构建步骤的顺序。请注意，如果您有一个从模板继承的构建配置，您无法重新排序继承的构建步骤。然而，您可以在任何位置以任何顺序插入自定义构建步骤（不继承），甚至可以在继承的构建步骤之前或者之间插入。只能在原始模板中重新排序继承的构建步骤。
您可以暂时或永久禁用构建步骤，即使它是从构建配置模板继承的，也可以使用构建步骤列表最后一列中的相应选项。

2026年 9月 11日