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

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

机制 信息 例子

命令行界面

配置构建行为和 Gradle 功能的标志

--rerun

项目属性

特定于您的 Gradle 项目的属性

TestFilter::isFailOnNoMatchingTests=false

系统属性

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

systemProp.http.proxyHost=somehost.org

等级属性

配置 Gradle 设置的属性

org.gradle.caching=true

环境变量

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

JAVA_HOME

配置优先级

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

优先事项 方法 地点 例子 细节

1

命令行标志

命令行

--build-cache

它们优先于属性和环境变量。

2

系统属性

项目根目录

systemProp.http.proxyPort=443

存储在gradle.properties文件中。

3

等级属性

GRADLE_USER_HOME
项目根目录
GRADLE_HOME

org.gradle.logging.level=quiet

存储在gradle.properties文件中。

4

环境变量

环境

GRADLE_OPTS

来自执行 Gradle 的环境。

项目属性

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

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

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

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

您有两个选项来添加项目属性，按优先级顺序列出：

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

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

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

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

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

以下示例将fooProject 对象的属性设置为"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。-D该命令的选项与该命令的选项gradle具有相同的效果。-Djava

    $ ./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 包装器下载 Gradle 发行版的密码。

gradle.user.home=(path to directory)

指定GRADLE_USER_HOME目录。

https.protocols

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

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

在多项目构建中，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 提供了多个选项，可以轻松配置用于执行构建的 Java 进程。虽然可以通过GRADLE_OPTS或在本地环境中配置这些JAVA_OPTS，但能够JAVA_HOME在版本控制中存储某些设置（例如 JVM 内存配置和位置）非常有用，以便整个团队可以在一致的环境中工作。

您有一种选择来添加 gradle 属性：

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

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

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

优先事项 方法 地点 细节

1

命令行界面

。

在命令行中使用-D.

2

gradle.properties文件

GRADLE_USER_HOME

存储gradle.properties在GRADLE_USER_HOME.

3

gradle.properties文件

项目根目录

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

4

gradle.properties文件

GRADLE_HOME

存储在可选 Gradle 安装目录gradle.properties中的文件中。GRADLE_HOME
的位置可能已通过命令行上传递的系统属性 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。请注意，这相当于添加-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005到 JVM 命令行，并将挂起虚拟机，直到连接调试器。

默认为false.

org.gradle.java.home=(path to JDK home)

指定 Gradle 构建过程的 Java 主目录。该值可以设置为 ajdk或jrelocation；但是，使用 JDK 更安全，具体取决于您的构建用途。这不会影响用于启动Gradle 客户端 VM的 Java 版本。

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

org.gradle.jvmargs=(JVM arguments)

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

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

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

当设置为安静、警告、信息或调试时，Gradle 将使用此日志级别。这些值不区分大小写。

默认为lifecycle水平。

org.gradle.parallel=(true,false)

配置完成后，Gradle 将分叉多个org.gradle.workers.maxJVM 来并行执行项目。

默认为false.

org.gradle.priority=(low,normal)

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

默认为normal.

org.gradle.projectcachedir=(directory)

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

默认为.gradle.

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

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

默认为false.

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

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

默认为false.

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

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

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

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

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

默认为summary.

org.gradle.workers.max=(max # of worker processes)

配置后，Gradle 将使用给定数量的最大工作人员。

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

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

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

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 参数。

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

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

GRADLE_USER_HOME

指定GRADLE_USER_HOMEGradle 存储其全局配置属性、初始化脚本、缓存、日志文件等的目录。

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

JAVA_HOME

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

该 VM 也用于守护进程，除非在 Gradle 属性文件中使用org.gradle.java.home.

GRADLE_LIBS_REPO_OVERRIDE

覆盖默认 Gradle 库存储库。

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

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

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

示例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')
}