Gradle

Gradle 构建运行程序运行 Gradle 项目。

要使用 Gradle 运行构建，所有代理机器上都必须安装 Gradle 0.9-rc-1 或更高版本。或者，如果您使用 Gradle wrapper ，您需要在您的版本控制中检入正确配置的 Gradle Wrapper 脚本。

运行器支持所有 Gradle 构建配置，包括 build.gradle 和 build.gradle.kts。

Gradle 参数

选项	描述
Gradle 任务	指定由空格分隔的 Gradle 任务名称。例如， `:myproject:clean :myproject:build` 或 `clean build`。如果此字段留空，则使用 'default' 任务。请注意，TeamCity 目前支持使用 Gradle 构建 Java 项目。构建 Groovy ，Scala 等其他项目尚未经过测试。其他的任务选项也应在此字段中输入。例如， `:myproject:run --args="foo --bar"` 或 `clean test --tests MyTestClass.myTestMethod`。
Gradle 构建文件	一条通往 Gradle 构建文件的路径，相对于工作目录。如果为空（默认），Gradle 使用自己的设置来确定它。要为 Gradle 9.0 及更高版本指定构建文件，请将 `-p <path to build file relative to the checkout directory>` 行添加到附加的 Gradle 命令行参数字段中，而不是使用此设置。
增量构建	TeamCity 可以利用 Gradle 的 `:buildDependents` 功能。如果启用了增量构建选项，TeamCity 将检测到受构建中更改影响的 Gradle 模块，并仅为这些模块启动 `:buildDependents` 命令。这将导致 Gradle 完全构建并只测试受更改影响的模块。
Gradle 主目录路径	在此指定 Gradle 主目录的路径（`bin` 目录的父目录）。如果未指定，TeamCity 将使用代理的 `GRADLE_HOME` 环境变量中指定的 Gradle。如果您的代理上没有安装 Gradle，您可以改用 Gradle wrapper。
附加的 Gradle 命令行参数	可选的以空格分隔的 Gradle 属性列表。例如， `-x test` （或 `--exclude-task test`）、 `--configuration-cache` 或 `-PmyProjectProperty=foo`。
Gradle Wrapper	如果启用，TeamCity 将在签出目录中查找 Gradle Wrapper 脚本，并使用上述字段指定的 Gradle 任务和额外的命令行参数来启动相应的脚本。在这种情况下， Gradle home path 中指定的 Gradle 和代理上安装的 Gradle 将被忽视。

运行参数

选项	描述
调试	选择记录调试信息复选框等同于添加 `-d` Gradle命令行参数。使用 `DEBUG` 日志级别运行 Gradle 可能会在构建日志中暴露敏感信息（在 Gradle 文档中了解更多信息）。在启用此模式之前，请确保只有受信任的用户才能查看日志。
堆栈跟踪	选择 Print stacktrace 复选框等同于添加 `-s` Gradle 命令行参数。

Java 参数

选项	描述
JDK	选择一个 JDK。本节详述了可用的选项。默认值为 `JAVA_HOME` 环境变量或代理自身的 Java。
JDK 主目录路径	当上方选择了 <Custom> 时，此选项便可用。使用此字段来指定用于运行构建的自定义 JDK 的路径。如果该字段为空，则会从代理机器的 `JAVA_HOME` 环境变量或在构建代理配置文件（`buildAgent.properties` ）中指定的 `env.JAVA_HOME` 属性读取JDK Home的路径。如果这些值未被指定，TeamCity 将使用构建代理进程本身的 Java home。
JVM 命令行参数	附加的 JVM 命令行参数允许您设置初始和最大堆大小，启用额外的日志记录，选择所需的字节码验证器模式等等。您可以指定标准的（例如以 `-` 开始，例如 `-verbose：[class\|module\|gc\|jni]` 或 `--dry-run` ）和非标准的（例如以 `-X` 开始，例如 `-Xmx<size>` 或 `-XstartOnFirstThread` ）JVM 选项。要指定多个命令行参数，使用空格作为分隔符。例如： -verbose:gc -Xdiag -Xcomp -Xmx512m -Xms256m

选项

描述

JDK

选择一个 JDK。本节详述了可用的选项。默认值为 JAVA_HOME 环境变量或代理自身的 Java。

JDK 主目录路径

当上方选择了 <Custom> 时，此选项便可用。使用此字段来指定用于运行构建的自定义 JDK 的路径。如果该字段为空，则会从代理机器的 JAVA_HOME 环境变量或在构建代理配置文件（buildAgent.properties ）中指定的 env.JAVA_HOME 属性读取JDK Home的路径。如果这些值未被指定，TeamCity 将使用构建代理进程本身的 Java home。

JVM 命令行参数

附加的 JVM 命令行参数允许您设置初始和最大堆大小，启用额外的日志记录，选择所需的字节码验证器模式等等。

您可以指定标准的（例如以 - 开始，例如 -verbose：[class|module|gc|jni] 或 --dry-run ）和非标准的（例如以 -X 开始，例如 -Xmx<size> 或 -XstartOnFirstThread ）JVM 选项。

要指定多个命令行参数，使用空格作为分隔符。例如：

-verbose:gc -Xdiag -Xcomp -Xmx512m -Xms256m

构建属性

在 Gradle 构建中，TeamCity 系统属性与 Java 系统属性不同。

常规的 Java 系统属性可以全局访问。使用 System.getProperty("my.property") 或 providers.systemProperty("my.property").get() 方法获取这些属性的值。
TeamCity 系统属性在构建初始化时写入到 Project 对象中。因此，只要 Project（项目） 可用，就可以在任何地方访问 TeamCity 系统属性（使用 project.hasProperty("property.name") 检查所需属性是否可用）。

参考 TeamCity 系统属性的推荐方式如下：

task printProperty {
    doLast {
        println "${teamcity['teamcity.build.id']}"
    }
}


    

tasks.register("printProperty") {
    doLast {
        val teamcity: Map<*,*> by project
        println("${teamcity["teamcity.build.id"]}")
    }
}

    

或者如果系统属性的名称是合法的名称标识符（例如， system.myPropertyName = myPropertyValue）：

task printProperty {
     doLast {
          println "$myPropertyName"
     }
}


    

tasks.register("printProperty") {
    doLast {
        val myPropertyName: String by project
        println("$myPropertyName")
    }
}

    

Docker 设置

在这个部分，您可以指定一个将被用于运行构建步骤的 Docker 镜像。

Code Coverage（代码覆盖率）

Gradle 构建运行程序支持基于 IDEA 代码覆盖率引擎和 JaCoCo 的代码覆盖率。

配置缓存

从2024.03版本开始，TeamCity Gradle runner 支持 configuration cache。此功能通过缓存配置阶段的结果并在后续构建中重用此缓存，显著提高了构建性能。

如果满足以下任何一种情况，配置缓存就会被启用：

--configuration-cache 参数已添加到运行器的附加的 Gradle 命令行参数字段中。
一个 gradle.properties 文件包括 org.gradle.configuration-cache=true （适用于 Gradle 8.1+）或 org.gradle.unsafe.configuration-cache=true （适用于旧版 Gradle）行。这既适用于项目的 gradle.properties 文件，也适用于 GRADLE_USER_HOME 目录中的文件。

当前限制和已知问题

在以下情况下，Gradle 配置缓存可能无法按预期工作：

如果虚拟构建（在并行测试或 Matrix Build 运行期间生成的那些）的运行顺序与创建缓存时的顺序不同。请参阅此 YouTrack 工单以获取更多信息： TW-86556。
如果 Clean Checkout（干净签出）已启用；
如果构建步骤在 Docker 或 Podman 容器内运行；
如果 Gradle 忽略配置缓存问题。
如果附加命令行参数列表包含了 Gradle Tooling API 不支持的参数（--daemon、 --停止 等等）。

构建参数其值始终会在每次构建中变化（例如， build.id 或 build.number ），只会在需要时加载。您仍然可以使用直接引用（例如， project.teamcity["build.number"] ）来获取这些属性的值，但是 findProperty() 方法（project.findProperty("build.number") ）不会产生任何结果。如果您需要在您的 Gradle 脚本中调用此方法，请使用以下解决方案：

创建一个新的配置参数，并将其映射到受影响的参数： MyBuildNumber=%build.number%。
创建一个新的系统属性，将其映射到您的新配置参数： system.buildNumber = %MyBuildNumber%。
在您的 Gradle 脚本中，使用 ${findProperty}("buildNumber")} 语法来获取所需的值。

请注意，这种解决方法会阻止您的构建配置重用配置缓存，因此，您可能还希望将其禁用。

最后修改日期： 2025年 8月 12日