Gradle 提供了多种机制来配置 Gradle 本身和特定项目的行为。

以下是使用这些机制的参考

机制 信息 示例

命令行界面

配置构建行为和 Gradle 特性的标志

--rerun

项目属性

特定于 Gradle 项目的属性

TestFilter::isFailOnNoMatchingTests=false

系统属性

传递给 Gradle 运行时 (JVM) 的属性

systemProp.http.proxyHost=somehost.org

Gradle 属性

配置 Gradle 设置的属性

org.gradle.caching=true

环境变量

根据环境配置构建行为的属性

JAVA_HOME

配置的优先级

在配置 Gradle 行为时，可以使用这些方法，但必须考虑它们的优先级。下表按从最高到最低的优先级（第一个优先）列出了这些方法

优先级 方法 位置 示例 详细信息

1

命令行标志

命令行

--build-cache

这些优先于属性和环境变量。

2

系统属性

项目根目录

systemProp.http.proxyPort=443

存储在 gradle.properties 文件中。

3

Gradle 属性

GRADLE_USER_HOME
项目根目录
GRADLE_HOME

org.gradle.logging.level=quiet

存储在 gradle.properties 文件中。

4

环境变量

环境

GRADLE_OPTS

由执行 Gradle 的环境提供。

项目属性

项目属性特定于 Gradle 项目。它们使用构建脚本中的块或直接在 project 对象中定义。

例如，项目属性myProperty是在构建文件中创建的

build.gradle
ext {
    myProperty = findProperty('myProperty') ?: 'Hello, world!'
}

println "My property value: ${project.ext.myProperty}"

你有两种添加项目属性的选项，按优先级列出

  1. 命令行：你可以通过-P命令行选项直接向你的Project对象添加属性。

    $ ./gradlew build -PmyProperty='Hi, world'

  2. 系统属性或环境变量：你可以使用专门命名的系统属性或环境变量设置项目属性。

    $ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'

如果环境变量名称看起来像ORG_GRADLE_PROJECT_prop=somevalue，那么 Gradle 将在你的项目对象上设置一个prop属性，其值为somevalue。Gradle 也支持系统属性，但命名模式不同，看起来像org.gradle.project.prop。

以下示例将把foo属性在你的项目对象上设置为"bar"。

示例 1：通过命令行设置项目属性。

$ ./gradlew build -Pfoo=bar

示例 2：通过系统属性设置项目属性。

gradle.properties
org.gradle.project.foo=bar

示例 3：通过环境变量设置项目属性。

$ export ORG_GRADLE_PROJECT_foo=bar

此功能非常有用，当你没有持续集成服务器的管理员权限，并且需要设置不容易看到的属性值时。由于你无法在该场景中使用-P选项，也无法更改系统级配置文件，因此正确的策略是更改持续集成构建作业的配置，添加与预期模式匹配的环境变量设置。这对于系统上的普通用户来说是不可见的。

你可以在构建脚本中通过使用其名称来访问项目属性，就像使用变量一样。

命令行标志

命令行界面和可用的标志在其自己的部分中描述。

系统属性

系统属性是在 JVM 级别设置的变量，并且 Gradle 构建过程可以访问。可以在构建脚本中使用System类访问系统属性。下面列出了常见的系统属性。

你有两种添加系统属性的选项，按优先级列出

  1. 命令行：使用-D命令行选项，你可以向运行 Gradle 的 JVM 传递一个系统属性。gradle命令的-D选项与java命令的-D选项具有相同的效果。

    $ ./gradlew build -Dgradle.wrapperUser=myuser

  2. gradle.properties文件：你也可以在gradle.properties文件中设置系统属性，前缀为systemProp

    gradle.properties
    systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword

以下为常见系统属性

gradle.wrapperUser=(myuser)

指定用户名以从使用 HTTP 基本身份验证的服务器下载 Gradle 发行版。

gradle.wrapperPassword=(mypassword)

使用 Gradle wrapper 指定下载 Gradle 发行版的密码。

gradle.user.home=(path to directory)

指定 GRADLE_USER_HOME 目录。

https.protocols

以逗号分隔的格式指定受支持的 TLS 版本。例如，TLSv1.2,TLSv1.3。

其他 Java 系统属性在此处列出 here。

在多项目构建中，除根项目之外的任何项目中设置的 systemProp 属性都将被忽略。只有根项目的 gradle.properties 文件将被检查以查找以 systemProp 开头的属性。

以下示例演示如何使用系统属性

示例 1：使用 gradle.properties 文件设置系统属性

gradle.properties
systemProp.system=gradlePropertiesValue

示例 2：在配置时读取系统属性

init.gradle.kts
// Using the Java API
println(System.getProperty("system"))
settings.gradle.kts
// Using the Java API
println(System.getProperty("system"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
build.gradle.kts
// Using the Java API
println(System.getProperty("system"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
init.gradle
// Using the Java API
println System.getProperty('system')
settings.gradle
// Using the Java API
println System.getProperty('system')

// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()
build.gradle
// Using the Java API
println System.getProperty('system')

// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()

示例 3：读取系统属性以在执行时使用

build.gradle.kts
tasks.register<PrintValue>("printProperty") {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.systemProperty("system")
}
build.gradle
tasks.register('printProperty', PrintValue) {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.systemProperty('system')
}

示例 4：从命令行设置系统属性 -D gradle.wrapperUser=username

$ gradle -Dsystem=commandLineValue

Gradle 属性

Gradle 提供了多个选项，可轻松配置用于执行构建的 Java 进程。虽然可以通过 GRADLE_OPTS 或 JAVA_OPTS 在本地环境中配置这些选项，但将某些设置（如 JVM 内存配置和 JAVA_HOME 位置）存储在版本控制中非常有用，以便整个团队可以使用一致的环境。

您有一个选项可添加 gradle 属性

  1. gradle.properties 文件：将这些设置放入 gradle.properties 文件中，并将其提交到您的版本控制系统。

    gradle.properties
    org.gradle.caching.debug=false

Gradle 考虑的最终配置是命令行和 gradle.properties 文件中设置的所有 Gradle 属性的组合。如果某个选项在多个位置配置，则在任何这些位置中找到的第一个选项获胜

优先级 方法 位置 详细信息

1

命令行界面

.

在命令行中使用 -D。

2

gradle.properties 文件

GRADLE_USER_HOME

存储在 GRADLE_USER_HOME 中的 gradle.properties 文件中。

3

gradle.properties 文件

项目根目录

存储在项目目录（然后是其父项目目录，直至项目根目录）中的 gradle.properties 文件中。

4

gradle.properties 文件

GRADLE_HOME

存储在 GRADLE_HOME 中的 gradle.properties 文件中，可选的 Gradle 安装目录。
GRADLE_USER_HOME 的位置可能已通过命令行上传递的 -Dgradle.user.home 系统属性事先更改。

以下属性是常见的 Gradle 属性

org.gradle.caching=(true,false)

当设置为 true 时，Gradle 将在可能的情况下重复使用任何先前构建的任务输出，从而生成更快的构建。

默认值为 false；构建缓存未启用。

org.gradle.caching.debug=(true,false)

当设置为 true 时，各个输入属性哈希和每个任务的构建缓存键将记录在控制台上。

默认值为 false。

org.gradle.configuration-cache=(true,false)

启用配置缓存。Gradle 将尝试重复使用先前构建的构建配置。

默认值为 false。

org.gradle.configureondemand=(true,false)

启用孵化的按需配置，Gradle 将尝试仅配置必要的项目。

默认值为 false。

org.gradle.console=(auto,plain,rich,verbose)

自定义控制台输出着色或详细程度。

默认值取决于 Gradle 的调用方式。

org.gradle.continue=(true,false)

如果启用，则在任务失败后继续任务执行，否则在任务失败后停止任务执行。

默认值为 false。

org.gradle.daemon=(true,false)

当设置为 true 时，Gradle Daemon 用于运行构建。

默认值为 true。

org.gradle.daemon.idletimeout=(# of idle millis)

Gradle Daemon 将在指定的空闲毫秒数后终止自身。

默认值为 10800000（3 小时）。

org.gradle.debug=(true,false)

当设置为 true 时，Gradle 将在启用远程调试的情况下运行构建，侦听端口 5005。请注意，这等同于向 JVM 命令行添加 -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005，并且会暂停虚拟机，直到调试器附加。

默认值为 false。

org.gradle.java.home=(JDK 主目录路径)

指定 Gradle 构建过程的 Java 主目录。该值可以设置为 jdk 或 jre 位置；但是，根据构建执行的操作，使用 JDK 更安全。这不会影响用于启动 Gradle 客户端 VM 的 Java 版本。

如果未指定设置，则默认值将从您的环境（JAVA_HOME 或 java 的路径）派生。

org.gradle.jvmargs=(JVM 参数)

指定用于 Gradle Daemon 的 JVM 参数。此设置对于 配置 JVM 内存设置 以提高构建性能特别有用。这不会影响 Gradle 客户端 VM 的 JVM 设置。

默认值为 -Xmx512m "-XX:MaxMetaspaceSize=384m"。

org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)

当设置为 quiet、warn、info 或 debug 时，Gradle 将使用此 日志级别。这些值不区分大小写。

默认值为 lifecycle 级别。

org.gradle.parallel=(true,false)

进行配置后，Gradle 将分叉最多 org.gradle.workers.max 个 JVM 以 并行执行项目。

默认值为 false。

org.gradle.priority=(low,normal)

指定 Gradle Daemon 及其启动的所有进程的 调度优先级。

默认值为 normal。

org.gradle.projectcachedir=(目录)

指定特定于项目的缓存目录。默认为根项目目录中的 .gradle。

默认值为 .gradle。

org.gradle.unsafe.isolated-projects=(true,false)

启用项目隔离，从而启用配置缓存。

默认值为 false。

org.gradle.vfs.verbose=(true,false)

在 监视文件系统 时配置详细日志记录。

默认值为 false。

org.gradle.vfs.watch=(true,false)

切换 监视文件系统。启用后，Gradle 会在构建之间重用它收集的文件系统信息。

在 Gradle 支持此功能的操作系统上，默认值为 true。

org.gradle.warning.mode=(all,fail,summary,none)

当设置为 all、summary 或 none 时，Gradle 将使用 不同的警告类型显示。

默认值为 summary。

org.gradle.workers.max=(最大工作进程数)

进行配置后，Gradle 将使用最多 给定的工作进程数。

默认值为 CPU 处理器的数量。

以下示例演示如何使用 Gradle 属性。

示例 1：使用 gradle.properties 文件设置 Gradle 属性

gradle.properties
gradlePropertiesProp=gradlePropertiesValue
gradleProperties.with.dots=gradlePropertiesDottedValue

示例 2：在配置时读取 Gradle 属性

settings.gradle.kts
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())

// Using Kotlin delegated properties on `settings`
val gradlePropertiesProp: String by settings
println(gradlePropertiesProp)
build.gradle.kts
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())

// Using Kotlin delegated properties on `project`
val gradlePropertiesProp: String by project
println(gradlePropertiesProp)
settings.gradle
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()

// Using Groovy dynamic names
println gradlePropertiesProp
println settings.gradlePropertiesProp

// Using Groovy dynamic array notation on `settings`
println settings['gradlePropertiesProp']
build.gradle
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()

// Using Groovy dynamic names
println gradlePropertiesProp
println project.gradlePropertiesProp

// Using Groovy dynamic array notation on `project`
println project['gradlePropertiesProp']

Kotlin 委托属性是 Gradle Kotlin DSL 的一部分。您需要将类型明确指定为 String。如果您需要根据属性的存在进行分支，您还可以使用 String? 并检查 null。

请注意，如果 Gradle 属性的名称中带点，则无法使用动态 Groovy 名称。您必须使用 API 或动态数组表示法。

示例 3：读取 Gradle 属性以便在执行时使用

build.gradle.kts
tasks.register<PrintValue>("printProperty") {
    // Using the API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.gradleProperty("gradlePropertiesProp")
}
build.gradle
tasks.register('printProperty', PrintValue) {
    // Using the API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.gradleProperty('gradlePropertiesProp')
}

示例 4：从命令行设置 Gradle 属性

$ gradle -DgradlePropertiesProp=commandLineValue

请注意，初始化脚本无法直接读取 Gradle 属性。可以在初始化脚本中读取最早的 Gradle 属性是在 settingsEvaluated {}

示例 5：从初始化脚本读取 Gradle 属性

init.gradle.kts
settingsEvaluated {
    // Using the API, provides a lazy Provider<String>
    println(providers.gradleProperty("gradlePropertiesProp").get())

    // Using Kotlin delegated properties on `settings`
    val gradlePropertiesProp: String by this
    println(gradlePropertiesProp)
}
init.gradle
settingsEvaluated { settings ->
    // Using the API, provides a lazy Provider<String>
    println settings.providers.gradleProperty('gradlePropertiesProp').get()

    // Using Groovy dynamic names
    println settings.gradlePropertiesProp

    // Using Groovy dynamic array notation on `settings`
    println settings['gradlePropertiesProp']
}

在子项目目录中存在的 gradle.properties 文件中声明的属性仅对该项目及其子项可用。

环境变量

Gradle 提供了许多环境变量，如下所示。您可以使用 System.getenv() 方法在构建脚本中将环境变量作为属性进行访问。

以下环境变量可用于 gradle 命令。

GRADLE_HOME

Gradle 的安装目录。

可用于指定本地 Gradle 版本，而不是使用包装器。

您可以将 GRADLE_HOME/bin 添加到 PATH 中，以用于特定应用程序和用例（例如，测试 Gradle 的早期版本）。

JAVA_OPTS

用于将 JVM 选项和自定义设置传递给 JVM。

GRADLE_OPTS

指定在启动 Gradle 客户端 VM 时要使用的 JVM 参数。

客户端 VM 仅处理命令行输入/输出，因此很少需要更改其 VM 选项。

实际构建由 Gradle 守护进程运行，它不受此环境变量影响。

GRADLE_USER_HOME

为 Gradle 指定 GRADLE_USER_HOME 目录，以便 Gradle 存储其全局配置属性、初始化脚本、缓存、日志文件等。

如果未设置，则默认为 USER_HOME/.gradle。

JAVA_HOME

指定用于客户端 VM 的 JDK 安装目录。

此 VM 也用于守护进程，除非在 Gradle 属性文件中使用 org.gradle.java.home 指定了其他 VM。

GRADLE_LIBS_REPO_OVERRIDE

覆盖默认的 Gradle 库存储库。

可用于在 org.gradle.plugins.ide.internal.resolver 中指定默认的 Gradle 存储库 URL。

如果您的公司使用防火墙/代理，则覆盖以指定内部托管的存储库非常有用。

以下示例演示了如何使用环境变量。

示例 1：在配置时读取环境变量

init.gradle.kts
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
settings.gradle.kts
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
build.gradle.kts
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
init.gradle
// Using the Java API
println System.getenv('ENVIRONMENTAL')
settings.gradle
// Using the Java API
println System.getenv('ENVIRONMENTAL')

// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()
build.gradle
// Using the Java API
println System.getenv('ENVIRONMENTAL')

// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()

示例 2：读取环境变量以在执行时使用

build.gradle.kts
tasks.register<PrintValue>("printValue") {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.environmentVariable("ENVIRONMENTAL")
}
build.gradle
tasks.register('printValue', PrintValue) {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.environmentVariable('ENVIRONMENTAL')
}