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

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

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=(myuser)

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

gradle.wrapperPassword=(mypassword)

指定使用 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.properties 文件中，这是可选的 Gradle 安装目录。
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=(# 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=(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 将 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=(最大工作进程数)

配置后，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 Daemon 运行，Gradle Daemon 不受此环境变量的影响。

GRADLE_USER_HOME

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

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

JAVA_HOME

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

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

GRADLE_LIBS_REPO_OVERRIDE

覆盖默认 Gradle 库仓库。

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

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