命令行界面是与 Gradle 交互的主要方式。

强烈建议使用包装器命令行来替代原有的命令行。

  • macOS / Linux：gradlew
  • Windows：gradlew.bat

执行 Gradle 命令行遵循如下结构：

1
gradle [taskName...] [--option-name...]

选项可以放在任务名称之前：

1
gradle [--option-name...] [taskName...]

指定多个任务名称时使用空格间隔开来：

1
gradle [taskName1 taskName2...] [--option-name...]

选项和参数之间可以使用或不使用=，但建议使用=：

1
gradle [...] --console=plain

启用某种行为的长格式选项可以加上前缀--no-来关闭这些行为：

1
2
gradle [...] --build-cache // 启用构建缓存
gradle [...] --no-build-cache // 关闭构建缓存

许多长格式选项都有其对应的短格式选项：

1
2
gradle --help
gradle -h

大部分命令行选项都可以在gradle.properties文件中配置相关属性来避免执行命令时输入它们，具体参考：https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties

使用命令

某些插件添加了自己的命令选项，比如，--tests是由 Java test filtering添加的。

执行任务命令语法

大多数构建都支持一组常见的被称为生命周期的任务，包含：build，assemble，check。

如果要在根项目执行一个名为task1的任务，执行如下命令：

1
gradle :task1

该命令会执行单个task1任务及其依赖的所有其他任务。

指定任务选项名称

为任务指定选项时给任务名称后的选项名称加上--前缀即可：

1
gradle task1 --task1option=task1value

消除任务选项歧义

由于插件选项名称可能会与内置选项具有相同的选项名称；在执行具有相同任务选项的内置任务和插件任务时，可以通过给内置选项加上--built-in前缀来消除选项歧义，解决任务冲突：

1
gradle [--built-in-option-name...] -- [taskName...] [--task-option-name...]

如果一个名为task1的任务接受一个名为--profile的选项：

  1. 执行gradle task1 --profile：此时--profile被视为内置选项。
  2. 执行gradle -- task1 --profile=value：此时--profile被视为任务选项。

多级项目执行任务

多级项目，在父项目执行子项目的任务时使用:号分隔子项目名称和任务名称，下面两种方式同：

1
gradle :subproject:taskName
1
gradle subproject:taskName

在父项目不指定子项目名称，仅指定任务名称时，将为所有子项目执行相同的任务：

1
gradle test

一些任务选择器，如，help、dependencies这种，只会在调用它们的项目上执行，不会在所有子项目上执行。

在子项目目录执行任务时，可以省略子项目名称：

1
cd subproject && gradke taskName

从子项目目录执行包装器时，记得使用相对路径引用执行gradlew，如，../gradlew taskName。

执行多个任务

执行任务时可以同时指定多个任务：

  1. 任务的依赖相关性决定了执行的精确顺序。
  2. 没有其他依赖的任务可能会比执行命令行时列出的任务更早执行。

举个栗子：

1
gradle test deploy

上述命令执行后将按照命令行中列出的顺序执行test和deploy任务，还将执行每个任务的依赖项。

命令顺序安全

尽管总是试图快速执行构建，但命令执行时的顺序安全也需要考虑，如以下代码：

1
gradle clean build

上述命令的顺序中隐含的意图是：先执行clean，再执行build。

在build后执行clean是不正确的，即使这样做会导致构建执行得更快，因为clean会删除build创建的内容。

相反，如果上述命令行的顺序是先build再clean，则在build之前执行clean是不正确的。虽然 Gradle 会尽快执行构建，但它也会尊重命令行上指定的任务顺序的安全性，并确保在按该顺序指定时，clean会在构建之前运行。

命令顺序安全依赖于任务正确声明它们创建、使用或删除的内容。

排除任务执行

可以使用-x或--exclude-task命令行选项并提供要排除的任务的名称来排除正在执行的任务：

1
gradle dist --exclude-task test

20240403161643

  • 即使dist任务依赖于test任务，test任务也不会被执行；test任务的依赖项compileTest，也没有被执行。
  • test与其他任务共同依赖的任务仍然会执行，比如，compile。

强制执行任务

可以使用--rerun-tasks选项强制执行所有任务，忽略最新检查：

1
gradle test --rerun-tasks

这将强制执行test任务和它的所有任务依赖项。

任务失败继续

快速失败默认构建行为，在任何任务失败时中止执行并使构建失败。这个行为可以使构建更快地完成，并防止级联故障混淆错误的原始异常，提升排查难度。

使用--continue选项强制在发生故障时继续执行每个任务：

1
gradle test --continue

当使用--continue选项时时，若构建中的每个任务的所有依赖项都已完成且没有失败，才会执行这个任务。

例如，如果测试任务执行时，发生了代码编译错误，则测试任务不会运行，因为test任务依赖于compilation任务。

如果任意的测试任务失败，很多测试套件会导致整个测试任务失败；比如，代码覆盖率和报告工具经常在测试任务之后运行，因此默认的快速失败行为可能会在这些工具运行之前停止执行。

名称缩略简写

执行命令并指定任务名称时，可以不提供任务的全名。

可以仅提供能辨别任务名称唯一性的部分，如：gradle che命令中的che足以被识别为check。

这个特性适用于项目名称，如：gradle lib:che是执行子项目library的check任务的缩写。

还可以使用更复杂的驼峰式缩写，这种方式会被展开并匹配驼峰式和短横线的名称，如，foBa（或fB）匹配fooBar和foo-bar。

更具体的一个例子：

1
gradle mAL:cT

输出如下：

1
2
3
4
5
> Task :my-awesome-library:compileTest
compiling unit tests

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

mAL:cT缩写匹配子项目my-awesome-library下的compileTest任务。

缩写也可以与-x命令行选项一起使用。

缩写展开追溯

对于复杂的项目，如果执行了预期的任务，则可能是模糊的。当使用缩写名称时，一个错别字可能导致执行意外的任务。

当启用INFO或更详细的日志级别时，执行任务会输出包含项目和任务名称缩写展开的额外信息。

比如，当执行mAL:cT，将会看到以下日志信息：

1
2
3
4
No exact project with name ':mAL' has been found. Checking for abbreviated names.
Found exactly one project that matches the abbreviated name ':mAL': ':my-awesome-library'.
No exact task with name ':cT' has been found. Checking for abbreviated names.
Found exactly one task name, that matches the abbreviated name ':cT': ':compileTest'.

常见任务

生成所有输出

在构建中通常委派build任务来打包所有产出物和运行所有的检查：

1
gradle build

运行应用程序

通常使用run任务运行应用程序，该任务打包应用程序并执行一些脚本或二进制文件：

1
gradle run

运行所有检查

所有验证检查任务（包括tests和linting）通常都使用check任务执行：

1
gradle check

清理构建产出

clean任务用于删除构建目录的内容，该任务预计算的要清理的构建产出物，会显著的提升后续任务执行时的额外构建时间：

1
gradle clean

项目报告

提供了几个内置的任务，可以显示项目构建的特定细节，这对于理解构建的结构和依赖关系以及调试问题非常有用。

列出项目

1
gradle projects

运行projects任务将勒出所选项目的子项目列表，该列表以层次结构显示。

列出任务

1
gradle tasks

运行tasks任务会为列出所选项目的主要任务列表报告，此列表显示项目的默认任务（如果有）以及每个任务的说明。

默认情况下，这个报告此只显示分配给任务组的任务。

在列出任务时，组（如验证、发布、帮助、构建……）可用作每个部分的标题：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
> Task :tasks

Build tasks
-----------
assemble - Assembles the outputs of this project.

Build Setup tasks
-----------------
init - Initializes a new Gradle build.

Distribution tasks
------------------
assembleDist - Assembles the main distributions

Documentation tasks
-------------------
javadoc - Generates Javadoc API documentation for the main source code.
  • --all：该选项在输出任务列表时可以输出更多的信息。
  • --no-all：将只输出分配给任务组的任务列表。
  • --group：该选项可以精确的显示指定的任务组下的任务，如，gradle tasks --group="build setup"。

任务详情

执行gradle help --task <task-name>会输出指定任务的详细信息：

1
gradle -q help --task libs

输出如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Detailed task information for libs

Paths
     :api:libs
     :webapp:libs

Type
     Task (org.gradle.api.Task)

Options
     --rerun     Causes the task to be re-run even if up-to-date.

Description
     Builds the JAR

Group
     build

此信息包括完整的任务路径、任务类型、可能的特定于任务的命令行选项以及给定任务的说明。

可以使用--types选项获取有关任务类类型的详细信息，也可以使用--no-types隐藏此信息。

依赖报告

构建扫描给予一个完整的、可视化的报告，显示哪些配置上存在哪些依赖项、可传递的依赖项和依赖项版本选择；使用--scan选项即可调用构建扫描功能。

1
gradle task1 --scan

执行后会提供一个指向基于 Web 页面的扫描报告链接地址，在该页面上可以看到与下面相似的依赖信息：

20240403161644

列出依赖

  • dependencies：该任务用于列出项目的依赖，并按配置进行细分，并以树形结构显示每个配置的直接和可传递性依赖关系。

    1
    gradle dependencies

    输出如下：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    > Task :app:dependencies

    ------------------------------------------------------------
    Project ':app'
    ------------------------------------------------------------

    compileClasspath - Compile classpath for source set 'main'.
    +--- project :model
    |    \--- org.json:json:20220924
    +--- com.google.inject:guice:5.1.0
    |    +--- javax.inject:javax.inject:1
    |    +--- aopalliance:aopalliance:1.0
    |    \--- com.google.guava:guava:30.1-jre -> 28.2-jre
    |         +--- com.google.guava:failureaccess:1.0.1
    |         +--- com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava
    |         +--- com.google.code.findbugs:jsr305:3.0.2
    |         +--- org.checkerframework:checker-qual:2.10.0 -> 3.28.0
    |         +--- com.google.errorprone:error_prone_annotations:2.3.4
    |         \--- com.google.j2objc:j2objc-annotations:1.3
    +--- com.google.inject:guice:{strictly 5.1.0} -> 5.1.0 (c)
    +--- org.json:json:{strictly 20220924} -> 20220924 (c)
    +--- javax.inject:javax.inject:{strictly 1} -> 1 (c)
    +--- aopalliance:aopalliance:{strictly 1.0} -> 1.0 (c)
    +--- com.google.guava:guava:{strictly [28.0-jre, 28.5-jre]} -> 28.2-jre (c)
    +--- com.google.guava:guava:{strictly 28.2-jre} -> 28.2-jre (c)
    +--- com.google.guava:failureaccess:{strictly 1.0.1} -> 1.0.1 (c)
    +--- com.google.guava:listenablefuture:{strictly 9999.0-empty-to-avoid-conflict-with-guava} -> 9999.0-empty-to-avoid-conflict-with-guava (c)
    +--- com.google.code.findbugs:jsr305:{strictly 3.0.2} -> 3.0.2 (c)
    +--- org.checkerframework:checker-qual:{strictly 3.28.0} -> 3.28.0 (c)
    +--- com.google.errorprone:error_prone_annotations:{strictly 2.3.4} -> 2.3.4 (c)
    \--- com.google.j2objc:j2objc-annotations:{strictly 1.3} -> 1.3 (c)

  • buildEnvironment：该任务用于可视化所选项目的buildscript依赖关系，类似于gradle dependencies任务可视化正在构建的软件的依赖关系。

    1
    gradle buildEnvironment

  • dependencyInsight：该任务可以让使用者深入了解与输入时指定的依赖项相匹配的特定依赖项（或多个依赖项）。

    1
    gradle dependencyInsight --dependency [...] --configuration [...]
    • --configuration：参数将结果限制为特定的配置，如，compileClasspath。

列出属性

properties任务用于列出所选项目的属性列表。

1
gradle -q api:properties

输出如下：

1
2
3
4
5
6
7
8
9
10
------------------------------------------------------------
Project ':api' - The shared API for the application
------------------------------------------------------------

allprojects: [project ':api']
ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler_Decorated@12345
asDynamicObject: DynamicObject for project ':api'
baseClassLoaderScope: org.gradle.api.internal.initialization.DefaultClassLoaderScope@12345

也可以使用--property参数查询指定的单个属性：

1
gradle -q api:properties --property allprojects

输出如下：

1
2
3
4
5
------------------------------------------------------------
Project ':api' - The shared API for the application
------------------------------------------------------------

allprojects: [project ':api']

命令补全

命令行补全功能提供bash和zsh环境下的 TAB 补全，支持任务、选项、属性的补全；但需要安装额外的补全组件。

调试选项

  • -?，-h，--help：显示内置命令选项的帮助信息，如果想要显示项目的上下文选项（如，查看指定任务的帮助信息）需要使用help任务而非该选项。
  • -v，--version：输出Gradle、Groovy、Ant、JVM和操作系统版本信息，并退出而不执行任何任务。
  • -V，--show-version：输出Gradle、Groovy、Ant、JVM和操作系统版本信息，并继续执行指定的任务。
  • -S，--full-stacktrace：输出出所有异常的完整（非常详细）堆栈跟踪。
  • -s，--stacktrace：输出用户异常（如，编译错误）的堆栈追踪。
  • --scan：创建关于构建的所有方面的细粒度信息的构建扫描。
  • -Dorg.gradle.debug=true：启用调试守护进程，默认的调试地址端口为localhost:5005。
  • -Dorg.gradle.debug.host=(host address)：指定启用调试时要监听或连接的主机地址，在 Java 9及更高版本的服务器模式中，为主机传递*将使服务器侦听所有网络接口；默认情况下，没有主机地址被传递给 JDWP，因此在 Java 9及更高版本中，使用了 JDWP 地址，而早期版本监听所有接口。
  • -Dorg.gradle.debug.port=(port number)：指定启用调试时要监听的端口号，默认值为5005。
  • -Dorg.gradle.debug.server=(true,false)：如果设置为true并且启用了调试，将使用调试器的socket-attach模式运行构建；否则，使用socket-listen模式，默认值为true。
  • -Dorg.gradle.debug.suspend=(true,false)：当设置为true并启用调试时，运行构建 JVM 将挂起，直到附加调试器，默认值为true。
  • -Dorg.gradle.daemon.debug=true：启用调试守护进程，与-Dorg.gradle.debug相同。

性能选项

在优化和提升构建性能时会用到这个部分的选项；其中大部分选项都可以在gradle.properties文件中指定，因此命令行标志不是必要的使用方式。

  • --build-cache，--no-build-cache：启用或禁用构建缓存，启用构建缓存时将尝试重用以前构建的产出物；默认禁用构建缓存。

  • --configuration-cache，--no-configuration-cache：启用或禁用配置缓存，启用配置缓存时将尝试重用以前构建中的构建配置；默认禁用配置缓存。

  • --configuration-cache-problems=(fail,warn)：设置配置缓存如何处理问题；默认值为fail。

    • warn：设置为该值时，只报告问题而不会导致构建失败。
    • fail：设置为该值时，如果存在任何问题，则构建失败。

  • --configure-on-demand，--no-configure-on-demand：启用或禁用按需配置，启用按需配置时将在构建时只配置关联的项目；默认禁用按需配置。

  • --max-workers：设置可以使用的最大工作进程数；默认值为处理器数量。

  • --parallel，--no-parallel：启用或禁用并行构建，有关此选项的限制，查阅并行构建项目；默认禁用并行构建。

  • --priority：指定守护程序及其启动的所有进程的调度优先级，值为normal或low；默认值为normal。

  • --profile：在layout.buildDirectory.dir("reports/profile")目录中生成高级性能报告，首推使用--scan生成性能报告。

  • --scan：生成包含详细性能诊断的构建扫描，如下：

    20240403161645

  • --watch-fs，--no-watch-fs：启用或禁用文件系统监视，启用文件系统监视时会重用在构建之间收集的有关文件系统的信息；默认会在支持此功能的操作系统上启用这个功能。

守护进程选项

下列的命令行选项用于管理守护进程：

  • --daemon，--no-daemon：启用或禁用守护进程来运行构建，如果没有运行中的守护进程或现有守护进程处于工作中，则启动新的守护进程；默认启动守护进程。
  • --foreground：以前台进程启动守护进程。
  • --status（独立命令）：执行gradle --status命令会列出正在运行和最近终止的守护程序；只显示同一版本的守护程序。
  • --stop（独立命令）：执行gradle --stop以终止相同版本的所有守护程序。
  • -Dorg.gradle.daemon.idletimeout=(number of milliseconds)：守护进程将在此毫秒数的空闲时间后自行停止；默认值为10800000毫秒，即3小时。

日志选项

设置日志等级

以下选项用于设置日志记录的详细程度，按详细度由低到高的顺序从上到下依次排列：

  • -Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug)：通过属性设置日志级别。
  • -q，--quiet：只输出错误日志。
  • -w，--warn：设置日志级别为warn。
  • -i，--info：设置日志级别为info。
  • -d，--debug：输出调试模式下的日志性息，包括堆栈信息。

默认日志级别为lifecycle。

定制日志格式

以下选项用于通过指定控制台模式来控制输出信息（颜色和字体变体）的丰富程度：

  • -Dorg.gradle.console=(auto,plain,rich,verbose)：通过属性设置控制台模式，不同的模式将在下面描述。
  • --console=(auto,plain,rich,verbose)：指定要生成的控制台输出类型。
    • auto（默认值）：当构建进程连接到控制台时，在控制台输出中启用颜色和其他丰富的输出，或者仅在未绑定到控制台时生成纯文本；这个选项是构建进程连接到终端时的默认设置。
    • plain：只生成纯文本，禁用控制台输出中的所有颜色和其他丰富输出；这个选项是构建进程未连接到终端时的默认设置。
    • rich：无论构建进程是否未连接到控制台，都可在控制台输出中启用颜色和其他丰富输出；当没有连接到控制台时，构建输出将使用 ANSI 控制字符来生成丰富的输出。
    • verbose：启用颜色和rich模式相同的及其他丰富输出，比如，在lifecycle日志级别输出任务名称和结果。

显示隐藏警告

默认情况下，不会显示所有警告（比如，弃用警告），运行时会把警告信息收集起来并在构建结束时呈现摘要，如：

1
Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0.

可以使用以下选项控制控制台上警告的详细程度：

  • -Dorg.gradle.warning.mode=(all,fail,none,summary)：通过属性指定警告模式，不同的模式将在下面描述。
  • --warning-mode=(all,fail,none,summary)：指定如何记录警告，默认为summary。
    • all：记录所有警告。
    • fail：记录所有警告，如果有任何警告则使构建失败。
    • summary：禁止显示所有警告并在构建结束时记录摘要。
    • none：禁止显示所有警告，包括构建结束时的摘要。

富控制台

富控制台在构建运行时展示额外的信息，如下：

20240403161646

特性：

  • 进度条和计时器直观地描述了整体状态。
  • 并行的工作进程描述了当前正在发生的事情。
  • 颜色和字体用于突出显示重要的输出和错误。

执行选项

以下选项通过更改构建内容或解析依赖项的方式来影响构建的执行方式：

  • --include-build：将构建作为组合构建运行，包括指定的构建。
  • --offline：在离线模式下运行构建。
  • -U，--refresh-dependencies：刷新依赖项的状态。
  • --continue：任务失败后继续执行任务。
  • -m，--dry-run：在禁用所有任务操作的情况下运行构建，使用此选项可以显示已执行的任务。
  • -t，-continuous：启用持续构建，进程不会退出，并将在任务文件输入更改时重新执行任务。
  • --write-locks：指定所有可锁定的已解析的配置都应保持其锁定状态。
  • --update-locks <group:name>[,<group:name>]*：指定必须在锁定文件中更新指定模块的版本，这个选项也意味着启用--write-locks。
  • -a，--no-rebuild：不再重新构建项目依赖项，在调试和微调buildSrc的情况下使用，但可能导致错误的结果；谨慎使用！

依赖验证

关于依赖验证的更详细内容见：https://docs.gradle.org/current/userguide/dependency_verification.html#verifying-dependencies

  • -F=(strict,lenient,off), --dependency-verification=(strict,lenient,off)：设置依赖验证的模式，默认模式为strict。
  • -M，--write-verification-metadata：为项目中使用的依赖项生成checksum（以逗号分隔），以进行依赖项验证。
  • --refresh-keys：刷新用于依赖项验证的公钥。
  • --export-keys：导出用于依赖项验证的公钥。

环境选项

下面的选项用于自定义有关构建脚本、设置、缓存等的许多方面。

  • -b，--build-file（已弃用）：指定构建文件，如：gradle --build-file=foo.gradle；默认为build.gradle，然后是build.gradle.kts。
  • -c，--settings-file（已弃用）：指定配置文件，如：gradle --settings-file=somewhere/else/settings.gradle。
  • -g，--gradle-user-home：指定 Gradle 用户目录，默认为系统当前用户目录下的.gradle目录。
  • -p，--project-dir：指定项目构建的起始位置，默认为当前目录。

任务选项

创建项目

持续构建