配置构建环境是自定义构建过程的强大方式。有许多可用的机制。通过利用这些机制，您可以使您的 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 属性文件

    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_USER_HOME 中查找用户级别的 gradle.properties 文件，然后是项目级别的 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 属性文件： 您还可以在 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 属性文件： 您还可以在 gradle.properties 文件中设置以 systemProp 为前缀的系统属性。

    gradle.properties
    systemProp.gradle.wrapperUser=myuser

系统属性参考

为了快速参考，以下是常用系统属性

gradle.wrapperUser=(我的用户)

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

gradle.wrapperPassword=(我的密码)

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

gradle.user.home=(目录路径)

指定 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 属性文件： 将这些设置放入 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 安装目录）中的 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 主目录路径)

指定 Gradle 构建过程的 Java 主目录。该值可以设置为 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 将分叉最多 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 是默认值。报告是根据提供给问题 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=(最大工作进程数)

配置后，Gradle 将使用最多给定数量的工作器。

默认值为 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 守护进程运行，该进程不受此环境变量的影响。

GRADLE_USER_HOME

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

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

JAVA_HOME

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

此 VM 也用于守护进程，除非在 Gradle 属性文件中使用 org.gradle.java.home 或使用守护进程 JVM 标准指定了不同的 VM。

GRADLE_LIBS_REPO_OVERRIDE

覆盖默认的 Gradle 库仓库。

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

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