配置构建参数

参数是 name=value 对，可以通过 TeamCity 设置和构建脚本中的 %parameterName% 语法引用。

参数的 值 部分可以是原始值（release.number=2026.1 ），也可以包含对其他参数的引用（system.tomcat.libs=%env.CATALINA_HOME%/lib/*.jar）。

参数类型

TeamCity 支持三种类型的参数：

配置参数 — 其主要目标是共享构建配置中的设置的参数。您还可以使用这些参数来自定义从 template创建或使用 recipe的配置。 TeamCity 不会将此类参数传递给构建过程（也就是说，这些参数对构建脚本引擎来说是无法访问的）。
环境变量 — 以 env. 前缀开头的参数。这些参数类似于系统的默认 env 变量，被传递给构建运行程序的过程。
系统属性 — 以 system. 前缀开头的参数。 TeamCity 可以将此类参数传递给某些运行器的配置文件，作为特定于构建工具的变量。

主要使用场景

参数化构建脚本

如果偶尔需要运行自定义脚本变体，可以用参数替换原始值。例如，以下 Kotlin DSL 示例展示了一个 Gradle 步骤，其默认运行 clean build 命令。

object GradleStepParameters : BuildType({
    params { param("gradle.task", "clean build") }
    steps {
        gradle {
            id = "gradle_runner"
            // runs "clean build" by default
            tasks = "%gradle.task%"
        }
    }
})

   

用户可以触发自定义构建来重写该参数并运行不同的 Gradle 任务。

还可以为该参数预填支持的值。然后，用户无需输入内容，可以通过组合框选择一个选项……

params {
    select("gradle.task", "clean build",
            options = listOf("clean build", "test build", "build assemble"))
}

   

…或复选框。

params {
    select("gradle.task", "clean build",
            allowMultiple = true, valueSeparator = "%space.separator%",
            options = listOf("clean", "test", "build", "assemble", "package"))
    param("space.separator", " ")
}

   

有关参数自定义的更多信息，请参见创建并设置自定义参数。

项目拥有的参数可以存储多个构建配置或流水线的通用设置。例如，如果组织对所有仓库都采用严格的分支命名准则，则无需为每个 VCS 根输入相同的分支规范和其他设置。

// Project level

params {
    param("default.branch.spec", """
            refs/heads/dev-*
            -:refs/heads/sandbox
            -:refs/heads/testing-*
        """.trimIndent())
    param("default.branch", "refs/heads/dev-2024.1")
}

// VCS Root

object GitHubRepoRoot : GitVcsRoot({
    name = "My Root"
    url = "..."
    branch = "%default.branch%"
    branchSpec = "%default.branch.spec%"
    authMethod = password {
        userName = "..."
        password = "..."
    }
})

   

避免使用原始值

TeamCity Agent 会报告一组参数，用于存储工具安装路径。可以在构建脚本和 TeamCity 设置中使用这些参数。这样可以创建与 Agent 无关的条件并减少潜在错误。

steps {
    gradle {
        name = "Gradle step"
        tasks = "build-dist"
        jdkHome = "%\env.JDK_19_0_ARM64%"
    }
}

   

在有些情况下，可能希望避免使用原始值，因为此类数据属于敏感信息（比如在构建脚本中使用的认证凭据）。要让这些敏感值在 TeamCity UI 和构建日志中隐藏，请创建密码参数。

自定义模板和配方

模板允许快速创建类似的构建配置和流水线。可以参数化部分模板设置，为每个从该模板派生的对象实现独特行为。

例如，以下构建配置包含两个步骤和布尔 skip.optional.step 参数。步骤＃2 的执行与否取决于此参数值。

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

object SourceConfig : BuildType({
    name = "SourceConfig"

    params {
        param("skip.optional.step", "false")
    }
    steps {
        script {
            name = "Mandatory Step"
            scriptContent = """echo "Mandatory step #1 is running...""""
        }
        script {
            name = "Optional Step"
            scriptContent = """echo "Optional step #2 is running...""""
            conditions {
                equals("skip.optional.step", "false")
            }
        }
    }})

   

如果您从此配置中提取一个模版，您可以创建同一配置的多个副本。在那些不需要运行可选步骤＃2的副本中，覆盖 skip.optional.step 参数并将其设置为 true。

import jetbrains.buildServer.configs.kotlin.*

object ConfigFromTemplate : BuildType({
    templates(SourceConfigTemplate)
    name = "Build Config Based on Template"

    params {
        param("skip.optional.step", "true")
    }
})

   

配方是用于封装常用操作的通用步骤。这些对象也通过参数自定义其行为。

<meta-runner name="cURL: File Download">
    <description>A two-step recipe that utilizes the "curl -o %URL% %fileName%" command to download a file, and calls "ls" command to print the contents of a working directory afterwards</description>
    <settings>
        <parameters>
            <param name="URL" value="" spec="text description='The URL of a file to be downloaded' display='normal' label='Download URL:'"/>
            <param name="fileName" value="" spec="text description='Enter the saved file name or leave blank to keep the origin name' label='File name:'" />
            <!--other parameters-->
        </parameters>
        <build-runners>
            <runner name="" type="simpleRunner">
                <parameters>
                    <param name="script.content" value="curl -o %URL% %fileName%" />
                    <param name="teamcity.step.mode" value="default" />
                    <param name="use.custom.script" value="true" />
                </parameters>
            </runner>
            <runner name="" type="simpleRunner">
                <parameters>
                    <param name="script.content" value="ls" />
                    <param name="teamcity.step.mode" value="default" />
                    <param name="use.custom.script" value="true" />
                </parameters>
            </runner>
        </build-runners>
        <requirements />
    </settings>
</meta-runner>

   

指定步骤执行条件。

您可以定义步骤执行条件来指定是否应运行单个步骤。您可以使用自定义和预定义的配置参数和环境变量来创建这些条件。

例如，您可以根据构建代理的操作系统运行不同的 shell 脚本。

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

object StepExecutionConditions : BuildType({
    params {
        param("win.destination.path", "C:/Sources")
        param("unix.destination.path", "/Users/Admin/Sources")
    }

    steps {
        // PowerShell script runs only on Windows agents
        powerShell {
            name = "Copy File (Windows)"
            conditions {
                startsWith("teamcity.agent.jvm.os.name", "Windows")
            }
            scriptMode = script {
                content = """
                    Copy-Item "%system.teamcity.build.workingDir%/result.xml" 
                    -Destination %win.destination.path%"""
            }
        }
        // Command Line runner for non-Windows agents
        script {
            name = "Copy File (Unix)"
            executionMode = BuildStep.ExecutionMode.RUN_ON_FAILURE

            conditions {
                doesNotContain("teamcity.agent.jvm.os.name", "Windows")
            }
            scriptContent = """
                cp "%system.teamcity.build.workingDir%/result.xml" 
                %unix.destination.path%"""
        }
    }
})

   

指定 Agent 要求

Agent requirements允许您指定 parameter-operator-value 条件。只有满足这些条件的代理才被允许构建此构建配置。

您可以只使用代理在构建开始之前可以报告其值的参数来定义代理要求。这些参数是：

所有代理可用的预定义配置参数（例如， teamcity.agent.name）。
由代理报告的环境变量（例如， env.DOTNET_SDK_VERSION）。
在代理的 buildAgent.properties 文件中存在的自定义配置参数（例如，在 TeamCity UI 中创建一个 custom.agent.parameter 并在代理的属性文件中添加 custom.agent.parameter=MyValue 行）。

在 Kotlin DSL 中，使用 要求 集合定义新要求。

object MyBuildConfig : BuildType({
    requirements {
        // Only agents with .NET SDK 5.0
        exists("DotNetCoreSDK5.0_Path")
        // Only Windows agents
        startsWith("teamcity.agent.jvm.os.name", "Windows")
        // Only agents with "Android" workload for .NET 7 SDK
        contains("DotNetWorkloads_7.0", "android")
    }
})

   

参数化构建器配置

.NET、 Maven、 Gradle、 Ant 和 NAnt 运行器允许您在构建配置文件中引用 TeamCity 参数。这种技术允许您将所需的值传递给构建过程。

在 .NET 中，使用 $(<parameter_name>) 语法传递参数值。

以下示例 .csproj 文件定义了两个自定义的 MSBuild 目标：

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <PropertyGroup>
        <OutputZipFile>project.zip</OutputZipFile>
        <OutputUnzipDir>unzipped</OutputUnzipDir>
    </PropertyGroup>

    <Target Name="Zip">
        <ItemGroup>
            <FilesToZip Include="project.proj*" />
        </ItemGroup>
        <Exec Command="dir" />
        <Microsoft.Build.Tasks.Message Text="##teamcity[progressMessage 'Archiving files to $(OutputZipFile) file...']"/>
        <Exec Command="PowerShell -command Compress-Archive @(FilesToZip, ',') $(OutputZipFile) -Force" />
    </Target>
    <Target Name="Unzip">
        <Microsoft.Build.Tasks.Message Text="##teamcity[progressMessage 'Unzipping files to $(OutputUnzipDir) folder...']"/>
        <Exec Command="PowerShell -command Expand-Archive $(OutputZipFile) -DestinationPath $(OutputUnzipDir) -Force" />
    </Target>
</Project>

     

要在 Maven 和 Ant 中引用参数值，请使用 ${parameterName} 语法。

<configuration>
    <tasks>
        <property environment="env"/>
        <echo message="TEMP = ${env.TEMP}"/>
        <echo message="TMP = ${env.TMP}"/>
        <echo message="java.io.tmpdir = ${java.io.tmpdir}"/>
        <echo message="build.number = ${build.number}"/>
    </tasks>
</configuration>

     

要在 Maven 和 Ant 中引用参数值，请使用 ${parameterName} 语法。

<target name="buildmain">
    <ant dir="${teamcity.build.checkoutDir}" antfile="${teamcity.build.checkoutDir}/build-test.xml" target="masterbuild_main"/>
</target>

     

对于 Gradle 运行器，TeamCity 系统属性可以被访问作为原生 Gradle 属性（那些在 gradle.properties 文件中定义的）。如果属性名称允许用作 Groovy 标识符（没有包含点），请使用以下语法：

println "Custom user property value is ${customUserProperty}"

否则，如果属性的名称中有点（例如， build.vcs.number.1 ），请使用 project.ext["build.vcs.number.1"] 语法代替。

参数来源

所有 TeamCity 参数可分为两大类：预定义和自定义（由 TeamCity 用户创建）。自定义参数可以在多个层级声明，包括单独的项目、构建配置和 Agent 机器。

预定义参数

TeamCity 提供多个预定义参数，可在构建工作流中引用。例如， teamcity.agent.work.dir.freeSpaceMb 参数报告该构建代理上的总可用空间，而 DotNetCLI_Path 参数返回 .NET CLI 的安装路径。

请参阅此文章以获取更多信息：预定义构建参数列表。

自定义模板、项目、配置和流水线参数

这些参数由用户在项目、配置和流水线设置中创建。在某些情况下，TeamCity 会自动创建这些参数。例如，如果 CLI 步骤运行 echo %MyParam% 命令，但 MyParam 不存在，则每次构建都会失败。 TeamCity 将此视为配置错误，除非为该缺失参数提供值，否则不会运行新构建。换句话说，缺失参数的存在会成为新构建的隐式要求。

有关更多信息，请参见创建并设置自定义参数和隐式要求。

自定义 Agent 参数

可以手动在 Agent 配置文件（<AGENT_HOME>/conf/buildAgent.properties ）中声明参数。例如，以下示例演示了如何实现自定义构建代理排名系统：

# An agent's "buildAgent.properties" files

######################################
#   Default Build Properties         #
######################################
# ...
agent.tier=Platinum
# ...

    

然后可以在 Agent 要求中使用该自定义 Agent 排名：

object Build : BuildType({
    name = "My build config"
    requirements {
        equals("agent.tier", "Platinum")
    }
})

    

自定义构建参数

触发自定义构建的用户可在相应的对话框选项卡上重写现有参数值并添加新参数。

例如，如果未为 Maven 构建步骤指定 Java 版本，则会使用代理的默认 Java（由 JAVA_HOME 环境变量定义）。如需重写，请在自定义构建运行对话框中添加 env.JAVA_HOME 参数，并将其设置为某个已存在的 Agent 参数，例如 %env.JDK_21_0_ARM64%。

动态创建的自定义参数

将 ##teamcity[setParameter name='foo' value='bar'] 服务消息输出到构建日志，以更新或新增参数。

参数值

TeamCity 参数可以从下列一个或多个来源获取其值。

从选定为强制设置模板的模板中获取的值。这些值不能被用户禁用或覆盖。
参数选项卡位于运行自定义构建对话框中。
为构建配置或流水线设置中的参数分配的自定义值。
为父项目设置中的参数分配的自定义值。在项目中定义的参数会被其所有子实体继承。
在常规构建配置模板中指定的值。
在构建代理的配置文件中指定的值（即 <AGENT_HOME>/conf/buildAgent.properties 文件）。
代理在连接到 TeamCity 服务器时报告的值。这些值被传递给描述代理环境的参数。例如， DotNetCoreSDK7.0_Path 参数用于存储此特定代理上 .NET 7 SDK 的路径。
预定义构建参数的值。这些参数可以在特定构建的服务器端范围内收集其值（例如， build.number 参数），或者在构建开始之前的代理端收集其值 (例如， teamcity.agent.work.dir.freeSpaceMb 参数)。

上述列表还按优先级从高到低排列了参数值来源。也就是说，如果同一个参数从不同的源获取不同的值，将会应用此列表中最顶端源的值。例如，如果 my.parameter 同时在 Agent 配置文件和构建配置中定义，则以配置设置页面中的值为准。

在构建过程中重写参数值

可以通过发送 ##teamcity[setParameter name='foo' value='bar'] 服务消息来重写初始参数值。请注意，通过这种方式修改的参数值只会在当前构建或构建链的作用域内生效。要永久地覆盖参数值，请从您的构建步骤中发送 REST API 请求，如下所示：

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

object UpdateBuildVersion : BuildType({
name = "Update Build Version"

    steps {
        script {
            id = "simpleRunner"
            scriptContent = """
                version=%\build.version%
                ((version=version+1))
                
                curl --location --request PUT 'http://<server_URL>/app/rest/projects/<project_name>/parameters/build.version' \
                --header 'Accept: */*' \
                --header 'Content-Type: text/plain' \
                --header 'Authorization: Bearer your_token' \
                --data ${'$'}version
            """.trimIndent()
        }
    }
})

   

从远程来源获取参数值

如需让敏感数据在 TeamCity UI 和构建日志中不可见（例如登录凭据、访问令牌），请使用可屏蔽其值的密码参数。为了进一步保护关键值，可将其存储在第三方金库中，并创建远程密钥类型的 TeamCity 参数。这些参数没有显式的"值"部分。而是存储了一个查询，TeamCity 每次需要解析参数引用时都会运行该查询。

目前，仅支持 HashiCorp Vault 作为远程密钥存储。请参阅此文章以获取更多信息： HashiCorp Vault 集成。

跟踪参数值

构建完成后，可在参数选项卡的构建结果页面中查看本次构建期间所有参数。 TeamCity 会高亮显示新参数及构建过程中值发生变更的参数。

要通过 REST API 检查特定构建的初始参数值和实际参数值，请向 /app/rest/builds/[{buildLocator}](https://www.jetbrains.com/zh-cn/help/teamcity/rest/buildlocator.html) 端点发送 GET 请求，并根据 Build schema 指定所需的负载字段。

/app/rest/builds/{buildLocator}?fields=originalProperties(*) — 返回构建配置中的用户定义参数及其默认值。
/app/rest/builds/{buildLocator}?fields=startProperties(*) — 返回代理报告的所有参数及其在构建开始时的值。
/app/rest/builds/{buildLocator}?fields=resultingProperties(*) — 返回代理报告的所有参数及其在构建完成时的值。

您也可以检查特定参数的初始值和最终值。为此，请指定目标参数的名称：

curl -L \
  https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=\
    originalProperties($locator(name:(value:(myParam),matchType:matches)),property),\
    startProperties($locator(name:(value:(myParam),matchType:matches)),property),\
    resultingProperties($locator(name:(value:(myParam),matchType:matches)),property)

   

2026年 8月 6日