配置 Agent 要求

代理要求是指定哪些代理可以运行您的构建配置的条件。要查看所有当前存在的需求并创建新需求，以及检查哪些代理可以运行特定配置，请转到构建配置设置 | 代理要求。

代理要求视频指南

需求语法

任何代理需求都是 参数运算符 [值] 表达式，其中：

形参 是预定义的或自定义（用户定义的）构建参数。例如， teamcity.agent.jvm.os.name 参数用于报告 agent 上安装的是哪种操作系统。请注意，由于需求应确定代理是否可以为此特定的构建配置运行构建，因此您应只使用取决于代理的参数值可能有所不同的参数。例如， teamcity.serverUrl 参数对任何代理报告相同的值，对于定义代理需求无用。
运算符 是一个关键词，定义了如何处理 值 部分。您可以在 "等于"、"开始于"、"不超过" 和其他运算符之间进行选择。请参阅此文章以获取完整列表：需求条件。
值 与参数报告的实际值进行比较。如果符合指定的条件，则整个表达式返回 true ，这意味着该代理与（能够运行构建的）这种特定配置是兼容的。某些运算符不需要值，例如 exists 运算符检查参数值是否不是 null 比较。 匹配项 和 不匹配 运算符允许您使用正则表达式来比较值。

显式需求

显式要求是在 Agent Requirements（代理要求）部分的构建配置设置或 Kotlin DSL 中手动配置的需求。

打开配置设置并导航到 Agent Requirements 设置选项卡。这个页面显示哪些代理当前有资格基于其执行的建筑常规来运行您的构建配置。
点击 添加新的需求 按钮。
选择一个参数，一个条件，并输入一个值来创建新的表达式。由于 TeamCity 扫描了代理报告的参数，因此在您输入参数名称和值时，它会显示出建议。
点击 Save。您的兼容和不兼容代理的列表将会进行更新。如果 TeamCity 无法找到满足您的新条件的代理，相应的警告将显示在需求旁边。运行此类构建配置将使构建在队列中等待，状态显示为“没有空闲的兼容代理可以运行此构建”。

Kotlin DSL

在 Kotlin DSL 中，向构建配置的 要求 块添加新表达式以创建显式需求。

object MyBuildConfig : BuildType({
requirements {
      exists("DotNetCoreSDK5.0_Path")
      startsWith("teamcity.agent.jvm.os.name", "Windows")
   }
})

    

参见：需求 | Kotlin DSL 文档

要暂时禁用或永久删除某个需求，请单击编辑旁边的下拉菜单按钮。

继承需求

如果在 Build Configuration Template（构建配置模板）中声明了代理需求，那么基于此模板的所有配置也会同样受到该需求的影响。 Agent Requirements（代理要求）页面将这些配置的需求标记为“继承”。

项目管理员可以编辑、禁用和移除继承的需求，除非它们是强制性设置模板的一部分。

构建步骤需求

构建步骤要求是项目管理员未手动创建的需求。它们是根据配置步骤的设置自动生成的。

例如，如果您的某个步骤被配置为在容器中运行，则分配处理此构建的代理必须具有容器引擎（Docker 或 Podman）。因此，TeamCity 会自动添加 docker.server.osType 存在 参数。未报告此参数的代理将不会被分配到此配置的新构建。

隐式要求

与构建步骤需求类似，隐式要求是 TeamCity 根据构建步骤配置自动添加的。然而，这些需求专注于参数引用。

例如，如果一个配置具有 echo "%myParam%" 命令行构建步骤，则意味着 myParam 参数存在并具有值。否则，如果参数缺失或为空，则没有内容可以输出。在这种情况下，TeamCity 会在参数选项卡上显示相应的警告...

...并在 Agent Requirements（代理要求）选项卡上显示相应的条目。

换句话说，隐式需求可以解释为“配置使用了未知参数”的警告。为了解决此问题，您需要在配置/项目级别提供参数值，或者在构建代理的 buildAgent.properties 文件中定义此参数。

## TeamCity build agent configuration file

######################################
#   Required Agent Properties        #
######################################

<...>

myParam="Hello world"

如果至少有一个代理报告了此参数，它将被列为兼容，并且隐式需求将从 Agent Requirements（代理要求）选项卡中隐藏。

单个步骤需求

除了配置范围的需求，您还可以为单个构建步骤定义代理需求。为此，请打开步骤设置并添加一个参数化执行条件。

结合条件

当定义了多个要求时，它们会被隐式地通过布尔值 AND 连接起来。例如，以下一组条件要求同时存在 env.JDK_17_0 参数和 env.JDK_21_0 参数：

requirements {
    exists("env.JDK_17_0")
    exists("env.JDK_21_0")
}

  

目前没有可用的机制来用布尔 OR 将需求连接起来。

最后修改日期： 2025年 3月 21日