配置构建环境是自定义构建过程的强大方式。有多种机制可用。通过利用这些机制，可以使 Gradle 构建更加灵活，并能适应不同的环境和要求。

可用机制

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

机制 信息 示例

命令行界面

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

--rerun

项目属性

特定于您的 Gradle 项目的属性

TestFilter::isFailOnNoMatchingTests=false

系统属性

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

http.proxyHost=somehost.org

Gradle 属性

配置 Gradle 设置以及执行构建的 Java 进程的属性

org.gradle.logging.level=quiet

环境变量

基于环境配置构建行为的属性

JAVA_HOME

配置优先级

配置 Gradle 行为时，可以使用这些方法，但必须考虑它们的优先级。

下表列出了这些方法，按优先级从高到低排列（第一个优先）

优先级 方法 位置 备注

1

命令行

> 命令行

标志优先于属性和环境变量

2

系统属性

> 项目根目录

存储在 gradle.properties 文件中

3

Gradle 属性

> GRADLE_USER_HOME
> 项目根目录
> GRADLE_HOME

存储在 gradle.properties 文件中

4

环境变量

> 环境变量

由执行 Gradle 的环境提供

以下是指定 JDK 安装目录的所有可能配置，按优先级排序

  1. 命令行

    $ ./gradlew exampleTask -Dorg.gradle.java.home=/path/to/your/java/home --scan

  2. Gradle Properties 文件

    gradle.properties
    org.gradle.java.home=/path/to/your/java/home

  3. 环境变量

    $ export JAVA_HOME=/path/to/your/java/home

gradle.properties 文件

Gradle 属性、系统属性和项目属性都可以在 gradle.properties 文件中找到

gradle.properties
# Gradle properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8

# System properties
systemProp.pts.enabled=true
systemProp.log4j2.disableJmx=true
systemProp.file.encoding = UTF-8

# Project properties
kotlin.code.style=official
android.nonTransitiveRClass=false
spring-boot.version = 2.2.1.RELEASE

您可以将 gradle.properties 文件放置在项目的根目录、Gradle 用户主目录（GRADLE_USER_HOME）或 Gradle 可选安装目录（GRADLE_HOME）中。

解析属性时，Gradle 首先查找项目级别的 gradle.properties 文件，然后是位于 GRADLE_USER_HOME 中的用户级别的 gradle.properties 文件，最后是位于 GRADLE_HOME 中的 gradle.properties 文件，项目级别属性优先于用户级别和安装级别属性。

项目属性

项目属性特定于您的 Gradle 项目，可用于定制构建。项目属性可以在构建文件中访问，并在执行构建时从外部源传入。在构建脚本中，可以使用 providers.gradleProperty() 惰性获取项目属性。

设置项目属性

您有四种方式添加项目属性，按优先级排序

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

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

  2. 系统属性： Gradle 为项目属性创建了特定命名的系统属性，您可以使用 -D 命令行标志或 gradle.properties 文件设置它们。对于项目属性 myProperty，创建的系统属性名为 org.gradle.project.myProperty。

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

  3. Gradle Properties 文件： 您也可以在 gradle.properties 文件中设置项目属性。

    gradle.properties
    myProperty='Hi, world'

  4. 环境变量： 您可以使用环境变量设置项目属性。如果环境变量名称类似于 ORG_GRADLE_PROJECT_myProperty='Hi, world'，则 Gradle 将在您的项目对象上设置一个名为 myProperty 的属性，其值为 Hi, world。

    $ export ORG_GRADLE_PROJECT_myProperty='Hi, world'

    这通常是向无人值守构建（例如在 CI 服务器上运行的构建）提供项目属性（尤其是敏感信息）的首选方法。

可以根据调用时指定的项目属性来改变任务的行为。假设您希望确保发布构建仅由 CI 触发。处理此问题的简单方法是使用 isCI 项目属性

build.gradle.kts
tasks.register("performRelease") {
    val isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.isPresent) {
            println("Performing release actions")
        } else {
            throw InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
build.gradle
tasks.register('performRelease') {
    def isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.present) {
            println("Performing release actions")
        } else {
            throw new InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
$ ./gradlew performRelease -PisCI=true --quiet
Performing release actions

请注意，只要您的 gradle.properties 文件包含 isCI=true，运行 ./gradlew performRelease 将产生相同的结果

gradle.properties
isCI=true
$ ./gradlew performRelease --quiet
Performing release actions

命令行标志

命令行界面及其可用标志在其自己的章节中进行了描述。

系统属性

系统属性是在 JVM 级别设置的变量，Gradle 构建过程可以访问它们。在构建脚本中，可以使用 providers.systemProperty() 惰性获取系统属性。

设置系统属性

您有两种方式添加系统属性，按优先级排序

  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

系统属性参考

作为快速参考，以下是常见的系统属性

gradle.wrapperUser=(myuser)

指定用户名，以便使用 HTTP 基本认证从服务器下载 Gradle 发行版。

gradle.wrapperPassword=(mypassword)

指定密码，以便使用 Gradle wrapper 下载 Gradle 发行版。

gradle.user.home=(directory 路径)

指定 GRADLE_USER_HOME 目录。

https.protocols

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

此处列出了更多 Java 系统属性。

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

Gradle 属性

Gradle 属性配置 Gradle 本身，通常名称为 org.gradle.\*。Gradle 属性不应在构建逻辑中使用，其值不应在构建脚本中读取/获取。

设置 Gradle 属性

您有两种方式添加 Gradle 属性，按优先级排序

  1. 命令行： 使用 -D 命令行选项，您可以传递一个 Gradle 属性

    $ ./gradlew build -Dorg.gradle.caching.debug=false

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

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

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

优先级 方法 位置 详情

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 安装目录）下的 gradle.properties 文件中。
GRADLE_USER_HOME 的位置可能已经通过命令行传递的 -Dgradle.user.home 系统属性事先更改。

Gradle 属性参考

作为参考，以下是常见的 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=(空闲毫秒数)

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 home 路径)

指定 Gradle 构建过程的 Java home。该值可以设置为 jdk 或 jre 位置；但是，根据您的构建做什么，使用 JDK 更安全。这不会影响用于启动Gradle 客户端 VM 的 Java 版本。

您也可以使用Daemon JVM 标准来控制运行 Gradle 本身的 JVM。

如果未指定此设置，则默认值从您的环境（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 将fork 最多 org.gradle.workers.max 个 JVM，以便并行执行项目。

默认为 false。

org.gradle.priority=(low,normal)

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

默认为 normal。

org.gradle.projectcachedir=(目录)

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

默认为 .gradle。

org.gradle.problems.report=(true|false)

启用 (true) 或禁用 (false) build/reports/problems-report.html 的生成。默认为 true。报告包含提供给Problems API的问题。

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=(最大worker进程数)

配置后，Gradle 将使用给定数量的最大 worker 数。

默认为 CPU 处理器数量。

环境变量

Gradle 提供了许多环境变量，如下所示。在构建脚本中，可以使用 providers.environmentVariable() 惰性获取环境变量。

设置环境变量

举例说明如何设置 $JAVA_HOME 环境变量

$ set JAVA_HOME=C:\Path\To\Your\Java\Home   // Windows
$ export JAVA_HOME=/path/to/your/java/home  // Mac/Linux

您可以在构建脚本中使用 System.getenv() 方法将环境变量作为属性访问

task printEnvVariables {
    doLast {
        println "JAVA_HOME: ${System.getenv('JAVA_HOME')}"
    }
}

环境变量参考

gradle 命令可用的环境变量如下

GRADLE_HOME

Gradle 的安装目录。

可以用来指定本地 Gradle 版本，而不是使用 wrapper。

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

JAVA_OPTS

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

export JAVA_OPTS="-Xmx18928m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6309m"

GRADLE_OPTS

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

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

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

GRADLE_USER_HOME

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

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

JAVA_HOME

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

该 VM 也用于 daemon，除非在 Gradle 属性文件中使用 org.gradle.java.home 或使用Daemon JVM 标准指定了不同的 VM。

GRADLE_LIBS_REPO_OVERRIDE

默认 Gradle 库仓库的覆盖。

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

如果您的公司使用防火墙/代理，此覆盖很有用，可以指定内部托管的仓库。