运行构建链

默认情况下，触发下游对象会在单个共享源快照上运行整个构建链。本文介绍如何触发链、仅运行其中一部分以及停止链。

触发链

推荐的方法是仅将触发器添加到链的最终（最下游）对象。触发该对象时，TeamCity 会自动将其所有上游依赖项加入队列。上游对象不需要自己的触发器。

这遵循 "考虑结果" 原则：在最终想要的构建上配置触发器，并让链引入所需的一切。

VCS 构建触发器还有另一个选项，可以改变构建链的触发行为。启用此选项后，即使在依赖项而不是最终构建中检测到更改，也会触发整个构建链。

让我们从示例中取出一个构建链： pack 设置—— 依赖于 ——测试—— 依赖于 ——编译。

在 pack 设置 配置中设置了 VCS 触发器后，当 TeamCity 检测到在 pack 设置 中的变更时，整个构建链通常会被触发；在 编译 中的变更只会触发 编译 ，而不会触发整个链条。如果您希望在 编译 中的 VCS 更改触发整个链，将带有 "在快照依赖中的更改上触发" 选项的 VCS 触发器添加到链的最终构建配置 pack 设置。这不会改变构建的执行顺序，而只会在任何快照依赖项发生更改时触发整个构建链。在此设置中， 编译 或 测试 构建配置不需要 VCS 触发器。

要让上游更改在下游对象中可见，请启用显示来自快照依赖项的更改选项（位于版本控制设置部分）。这会在下游对象的更新日志和待处理的更改选项卡中显示上游更改。

无论此默认设置如何，用户在查看构建的更改列表时都可以包含或排除源自依赖项的更改。

重新运行失败的链构建

构建失败通常分为两个类别：每次运行都会再次出现的真正失败（语法错误、缺少引用），以及普通重试即可解决的临时性失败 — 不稳定测试、检出异常或暂时不可用的外部资源（AWS S3、Dockerhub、NuGet、maven.org 等）。为了解决链远端的暂时性失败而重新运行整个链可能成本很高，因此 TeamCity 提供了三种方式来重试失败的构建，而无需重启整个链。

自动重试

如果构建因基础架构问题而无法继续（例如，TeamCity 与其代理失去连接），TeamCity 会自动启动替代构建，这适用于独立构建和链构建。这不需要手动配置。

重试构建触发器

向配置添加重试构建触发器，以便在上一个构建失败时自动启动新构建。

import jetbrains.buildServer.configs.kotlin.*

object BuildB : BuildType({
    name = "Build B"

    steps { ... }

    triggers {
        retryBuild {
            branchFilter = ""
        }
    }

    dependencies { ... }
})

   

对于属于链一部分的配置，还要启用触发一个新的构建，使用相同的修订版本。 TeamCity 随后会复用上一次链运行中的每个成功构建，并且只在同一修订上重新构建失败的依赖项。

此触发器不会暂停链：新的构建会加入队列以替换失败的构建，但下游构建会基于原始失败继续进行。因此，下游构建最终仍可能因 "快照依赖项失败" 错误而变为红色。

依赖项重试设置

与重试触发器不同，依赖项重试设置会使下游构建等待。如果直接或间接快照依赖项失败，TeamCity 会延迟下游构建，并在继续之前自动重试失败的依赖项，直到达到设置的尝试次数。重试待处理期间，未成功的上游构建会被标记为已取消，而不是失败。

可以在构建配置设置的依赖选项卡中配置这些设置。

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

object DownstreamBuild : BuildType({
    name = "Downstream build"

    steps { ... }
    
    dependencies {
        snapshot(UpstreamBuild) { ... }
        retrySettings {
            maxAttempts = 3
            retryOnSameFailure = true
        }
    }})

   

使用自定义重试设置: 为此配置显式设置重试行为。否则，在启用使用最近的依赖（下游）构建中的重试设置后，该配置会从依赖它的任意构建继承其设置。可以在链中的最后一个配置上定义一次重试设置，并将其应用于未定义自身设置的每个上游构建。
即使失败原因相同也重试依赖项: 即使每次尝试都因相同原因失败，也会让 TeamCity 持续重试失败的依赖项，直到成功或尝试次数用尽。如果禁用，重复失败会保持原样，不会再次重试。

部分链执行

有时只需要运行链的一部分。 TeamCity 提供了三种机制，从临时方式到完全自动化方式均可。

提升构建

有时并不想从最开始运行链，而是想复用某个特定的已完成构建，并从那里继续链。打开该构建的结果页面，点击操作 | 提升，TeamCity 会将此构建作为源来触发链的下游部分。

这对两种常见场景很有用：

重用较早构建的结果，而不是最新结果。例如，将一次成功的 "构建 Docker 镜像" 运行提升到 "上传到 DockerHub" 配置或流水线，以重新部署同一工件而无需重新构建。
手动启动没有自动触发器的下游对象 — 例如，只想按需运行的部署配置。

提升是一次性重写：它只影响此次特定运行。之后，构建配置和流水线都会恢复到其正常的依赖项逻辑（最新成功或固定的构建）。

按需跳过构建

对于一次性的部分运行，请使用运行自定义构建对话框。在依赖选项卡上，为要忽略的任何直接链接配置设置跳过选项。

只能跳过与所触发对象直接链接的配置。对于 "构建 1 → 构建 2 → 构建 3 → 构建 4" 链，启动 "构建 4" 时只能跳过 "构建 3"。

带标记的条件依赖项

对于可重复的设置，请使用 teamcity.build.chain.skipTags 和 teamcity.build.chain.onlyTags 配置参数（自 2024.12 起可用）。

teamcity.build.chain.skipTags — 排除匹配的配置。链会运行除它们之外的所有内容。
teamcity.build.chain.onlyTags — 保留匹配的配置及其依赖项。保留的配置之间的配置无法跳过。

两个参数都接受由逗号分隔的以下列表：

标签 — teamcity.configuration.tags 参数的值，可在任何要添加标签的配置上设置。
配置 ID — 显示在配置设置中，或从配置 URL 复制。

TeamCity 仅来自触发该链的配置读取这些参数；依赖项构建上的值会被忽略。

示例：skipTags

一个复合 "全部构建" 配置会触发完整链。要让它只运行核心 "构建..." 配置并跳过可选测试，请给可选配置加标记并引用该标记：

object TestWin : BuildType({
    id("TestWin")
    params { param("teamcity.configuration.tags", "optional") }
})
// ... other optional configurations tagged "optional" ...

object BuildAll : BuildType({
    id("BuildAll")
    type = BuildTypeSettings.Type.COMPOSITE
    params {
        param("teamcity.build.chain.skipTags", "optional")
    }
    dependencies {
        snapshot(BuildWin) {}
        snapshot(BuildPlugins) {}
    }
})

    

若要改为运行完整链，请移除该参数，或将其设置为不匹配任何内容的值。一种常见模式是使用计划触发器重写完整夜间构建的值：

triggers {
    schedule {
        schedulingPolicy = daily { hour = 3 }
        triggerBuild = always()
        buildParams {
            param("teamcity.build.chain.skipTags", "nightly-build-mode")
        }
    }
}

    

示例：onlyTags

要让用户在触发时选择子链，请将 onlyTags 设置为带有 "提示" 显示模式的选择参数：

object BuildAll : BuildType({
    id("BuildAll")
    type = BuildTypeSettings.Type.COMPOSITE
    params {
        select("teamcity.build.chain.onlyTags", "",
            label = "Choose a sub-chain to run",
            display = ParameterDisplay.PROMPT,
            options = listOf(
                "run all" to "",
                "windows" to "windows",
                "linux" to "linux",
                "plugins" to "plugins"))
    }
    dependencies {
        snapshot(BuildWin) {}
        snapshot(BuildLinux) {}
        snapshot(BuildPlugins) {}
    }
})

    

手动触发时，运行自定义构建对话框会提示用户选择一个值。空值会运行整个链；标记只会运行带有该标记的配置及其依赖项。

在运行时跳过排队的构建

要从正在运行的构建步骤中动态取消排队的下游构建，请发送服务消息：

##teamcity[skipQueuedBuilds tags='value1,value2' comment='Your comment']

标记 实参接受与上述参数相同的标记和配置 ID。这对于根据运行时条件取消链的特定分支很有用 — 例如，从 "构建" 步骤中跳过选定的测试套件：

Build ----|---- Test Suite 1 ----|
          |---- Test Suite 2 ----|---- Deploy
          |---- Test Suite 3 ----|

   

避免跳过整个中间部分，否则会留下令人困惑的 "构建 → ？？？ → 部署" 空缺。在这种情况下，请改为维护一个单独的精简链。

停止链构建

当停止或从队列中移除属于链一部分的构建时，TeamCity 会显示消息 "此构建是构建链的一部分"，并在停止其他部分下列出其他正在运行或排队的链成员。

列出的每个可访问构建都有一个复选框。如果停止当前构建必然会导致该构建失败，则默认选中该复选框。
没有停止权限的构建会显示为不带复选框。
没有查看权限的构建会被隐藏，并替换为一条警告，提示无法看到链的所有部分。

如果链的所有其他部分都已完成，则不会显示其他信息。

在链中运行个人构建

当个人构建触发链时，其所有上游依赖项也会作为个人构建运行。例外情况是构建复用：如果启用了复用，并且已完成的非个人构建满足修订要求，TeamCity 会使用该构建，而不是运行不会增加价值的个人上游构建。

2026年 9月 11日