Gradle
此构建步骤专为构建 Gradle 项目而设计，并支持所有 Gradle 构建配置，包括 build.gradle 和 build.gradle.kts。
前提条件
要使用 Gradle 运行构建，所有代理机器上都必须安装 Gradle 0.9-rc-1 或更高版本。 或者，如果您使用 Gradle wrapper ，您需要在您的版本控制中检入正确配置的 Gradle Wrapper 脚本。
步骤设置
Gradle 步骤设置及其对应 UI 标签的列表会根据您是配置构建配置还是流水线而略有不同。
主要设置
- 任务
此步应执行的以空格分隔的 Gradle 任务列表。 例如，
:myproject:clean :myproject:build或clean build。 如果此字段留空，将使用默认任务。 请注意，TeamCity 目前支持使用 Gradle 构建 Java 项目。 构建 Groovy ，Scala 等其他项目尚未经过测试。其他的 任务选项也应在此字段中输入。 例如，
:myproject:run --args="foo --bar"或clean test --tests MyTestClass.myTestMethod。- 工作目录
构建步骤启动的目录。 默认情况下，这是代理签出远程资源的根目录。 有关更多信息，请参阅此主题： 构建工作目录。
- 使用 Gradle 包装器
启用后，TeamCity 将在签出目录中查找 Gradle 包装器脚本，并使用步骤设置中指定的 Gradle 任务和其他命令行参数启动相应脚本。 在这种情况下，将忽略 Gradle 主目录 路径中指定的 Gradle 以及代理上安装的 Gradle。
其他设置
- Gradle 主目录
Gradle 主目录的路径（即
bin目录的父目录）。 如果未指定，TeamCity 将使用代理的GRADLE_HOME环境变量中指定的 Gradle。 如果您的代理上没有安装 Gradle，您可以改用 Gradle wrapper。- 构建文件
一条通往 Gradle 构建文件 的路径，相对于工作目录。 如果为空（默认），Gradle 使用自己的设置来确定它。
- 附加的 Gradle 命令行参数
可选的以空格分隔的 Gradle 属性列表。 例如，
-x test（或--exclude-task test）、--configuration-cache或-PmyProjectProperty=foo。- Gradle 包装器路径
相对于工作目录的 Gradle 包装器脚本的可选路径。
- 增量构建
TeamCity 可以利用 Gradle 的
:buildDependents功能。 如果启用了 增量构建 选项，TeamCity 将检测到受构建中更改影响的 Gradle 模块，并仅为这些模块启动:buildDependents命令。 这将导致 Gradle 完全构建并只测试受更改影响的模块。
运行参数
- 调试
添加
-dGradle 命令行参数。- 堆栈跟踪
添加
-sGradle 命令行参数。
容器设置
此构建步骤可在由 Docker 或 Podman 部署的容器中运行。
传统构建配置步骤显示一组属性，允许您指定镜像名称、平台和附加运行参数。 显式拉取镜像 可确保 TeamCity 每次运行此步骤时都从目标容器拉取镜像。
要为 TeamCity 指定拉取镜像的注册表，请将 Docker/Podman 连接 添加到项目中。 默认情况下，此连接允许 TeamCity 以匿名模式从 Docker Hub 拉取镜像，但您可以将其配置为使用任何容器注册表。
有关更多信息，请参阅以下文章： 容器包装器。
启用 在 Docker 中运行 以在容器中运行步骤。 启用后，此元素会显示两个选项。
Docker 镜像 — 允许您从 Docker 或 Podman 注册表中拉取镜像。 默认情况下，TeamCity 可在匿名模式下从 Docker Hub 拉取镜像。 对于其他情况（私有镜像、自定义镜像注册表、非匿名模式以避免违反 Docker Hub 速率限制），请在流水线或作业级别配置 Docker 集成。
Dockerfile — 允许您从 Dockerfile 构建自定义镜像。
Code Coverage（代码覆盖率）
Gradle 构建运行程序支持基于 IDEA 代码覆盖率引擎 和 JaCoCo 的代码覆盖率。
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
构建属性
在 Gradle 构建中，TeamCity 系统属性与 Java 系统属性不同。
常规的 Java 系统属性可以全局访问。 使用
System.getProperty("my.property")或providers.systemProperty("my.property").get()方法获取这些属性的值。TeamCity 系统属性 会在构建初始化时写入 Project 对象。 因此，只要
Project（项目）可用，就可以在任何地方访问 TeamCity 系统属性（使用project.hasProperty("property.name")检查所需属性是否可用）。
参考 TeamCity 系统属性的推荐方式如下：
或者如果系统属性的名称是合法的名称标识符（例如， system.myPropertyName = myPropertyValue）：
配置缓存
从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")}语法来获取所需的值。
请注意，这种解决方法会阻止您的构建配置重用配置缓存，因此，您可能还希望将其禁用。
配置即代码
以下代码段展示了以 YAML （仅限流水线）和 Kotlin DSL 格式自定义的构建步骤。