命令行界面是**与 Gradle 交互的主要方法**。
以下是执行和自定义 Gradle 命令行的参考。它也用作编写脚本或配置持续集成的参考。
**强烈建议使用Gradle Wrapper**。在以下示例中，将./gradlew（在 macOS / Linux 中）或gradlew.bat（在 Windows 中）替换为gradle。
在命令行上执行 Gradle 符合以下结构
gradle [taskName...] [--option-name...]
选项允许在任务名称之前和之后。
gradle [--option-name...] [taskName...]
如果指定了多个任务，则应使用空格将它们隔开。
gradle [taskName1 taskName2...] [--option-name...]
接受值的选项可以使用或不使用=在选项和参数之间指定。建议使用=。
gradle [...] --console=plain
启用行为的选项具有长格式选项，其反向选项使用--no-指定。以下是相反的。
gradle [...] --build-cache gradle [...] --no-build-cache
许多长格式选项都有短格式选项等效项。以下是等效的
gradle --help gradle -h
许多命令行标志可以在gradle.properties中指定，以避免需要键入。有关详细信息，请参阅配置构建环境指南。
|
命令行使用
以下部分描述了 Gradle 命令行界面的使用。
执行任务
您可以在项目报告部分了解可用的项目和任务。
大多数构建都支持一组称为生命周期任务的通用任务。这些包括build、assemble和check任务。
要执行根项目上的名为myTask的任务，请键入
$ gradle :myTask
这将运行单个myTask及其所有依赖项。
指定任务选项
要将选项传递给任务，请在任务名称后使用--作为前缀
$ gradle exampleTask --exampleOption=exampleValue
区分任务选项和内置选项
Gradle 不会阻止任务注册与 Gradle 内置选项（如--profile或--help）冲突的选项。
您可以使用命令中任务名称之前的--分隔符来修复与 Gradle 内置选项冲突的任务选项
$ gradle [--built-in-option-name...] -- [taskName...] [--task-option-name...]
考虑一个名为mytask的任务，它接受一个名为profile的选项
-
在
gradle mytask --profile中，Gradle 将--profile作为内置 Gradle 选项接受。 -
在
gradle -- mytask --profile=value中，Gradle 将--profile作为任务选项传递。
在多项目构建中执行任务
在多项目构建中，可以使用:分隔子项目名称和任务名称来执行子项目任务。以下在从根项目运行时是等效的
$ gradle :subproject:taskName
$ gradle subproject:taskName
您还可以使用仅包含任务名称的任务选择器来运行所有子项目的任务。
以下命令从根项目目录调用时，将在所有子项目上运行test任务
$ gradle test
一些任务选择器，如help或dependencies，只会对它们调用的项目运行任务，而不会对所有子项目运行。
|
从子项目内部调用 Gradle 时，应省略项目名称
$ cd subproject
$ gradle taskName
从子项目目录执行 Gradle Wrapper 时，请相对引用gradlew。例如：../gradlew taskName。
|
执行多个任务
您还可以指定多个任务。任务的依赖项决定了执行的确切顺序，并且没有依赖项的任务可能比在命令行中列出的顺序更早执行。
例如，以下将按命令行中列出的顺序执行test和deploy任务，并将执行每个任务的依赖项。
$ gradle test deploy
命令行顺序安全
虽然 Gradle 始终会尝试快速执行构建，但也会遵守命令行顺序安全。
例如，以下命令将执行 clean 和 build 以及它们的依赖项
$ gradle clean build
但是，命令行顺序中隐含的意图是 clean 应该先运行，然后是 build。在 build 之后执行 clean 是不正确的，即使这样做会导致构建更快执行，因为 clean 会删除 build 创建的内容。
相反，如果命令行顺序是 build 后跟 clean，则在 build 之前执行 clean 是不正确的。虽然 Gradle 会尽快执行构建，但它也会尊重命令行上指定的任务顺序的安全，并确保在指定顺序时 clean 在 build 之前运行。
请注意，命令行顺序安全 依赖于任务正确声明它们创建、使用或删除的内容。
从执行中排除任务
您可以使用 -x 或 --exclude-task 命令行选项并提供要排除的任务名称来排除任务的执行
$ gradle dist --exclude-task test
> Task :compile compiling source > Task :dist building the distribution BUILD SUCCESSFUL in 0s 2 actionable tasks: 2 executed
您可以看到 test 任务没有执行，即使 dist 任务依赖于它。test 任务的依赖项，例如 compileTest，也没有执行。test 的其他任务依赖的依赖项，例如 compile，仍然执行。
强制执行任务
您可以使用 --rerun-tasks 选项强制 Gradle 执行所有任务，忽略 最新检查
$ gradle test --rerun-tasks
这将强制执行 test 和 test 的所有任务依赖项。它类似于运行 gradle clean test，但不会删除构建的生成输出。
或者，您可以告诉 Gradle 重新运行特定任务，使用 --rerun 内置的 任务选项.
任务失败后继续构建
默认情况下，当任何任务失败时，Gradle 会中止执行并使构建失败。这允许构建更快完成，并防止级联故障掩盖错误的根本原因。
您可以使用 --continue 选项强制 Gradle 在发生故障时执行每个任务。
$ gradle test --continue
当使用 --continue 执行时，如果该任务的所有依赖项都已完成且未发生故障，Gradle 会执行构建中的每个任务。
例如，如果被测代码中存在编译错误，则测试不会运行，因为 test 任务依赖于 compilation 任务。Gradle 在构建结束时输出遇到的每个故障。
如果任何测试失败，许多测试套件会使整个 test 任务失败。代码覆盖率和报告工具通常在测试任务之后运行，因此“快速失败”行为可能会在这些工具运行之前停止执行。
|
名称缩写
在命令行上指定任务时，您不必提供任务的完整名称。您可以提供足够的任务名称来唯一标识该任务。例如，gradle che 很可能足以让 Gradle 识别 check 任务。
项目名称也是如此。您可以使用 gradle lib:che 命令在 library 子项目中执行 check 任务。
更具体地说，您可以使用命令 gradle mAL:cT 在 my-awesome-library 子项目中运行 compileTest 任务。
$ gradle mAL:cT
> Task :my-awesome-library:compileTest compiling unit tests BUILD SUCCESSFUL in 0s 1 actionable task: 1 executed
缩写也可以与 -x 命令行选项一起使用。
跟踪名称扩展
对于复杂的项目，可能不清楚是否执行了预期的任务。使用缩写名称时，一个简单的拼写错误会导致执行意外的任务。
当启用 INFO 或更 详细的日志记录 时，输出将包含有关项目和任务名称扩展的额外信息。
例如，在前面的示例中执行 mAL:cT 命令时，将显示以下日志消息
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'.
项目报告
Gradle 提供了几个内置任务，用于显示构建的特定详细信息。这对于理解构建的结构和依赖关系以及调试问题很有用。
列出任务
运行 gradle tasks 会显示所选项目的主要任务列表。此报告显示项目的默认任务（如果有）以及每个任务的描述。
$ gradle tasks
默认情况下，此报告仅显示分配给任务组的任务。
组（例如验证、发布、帮助、构建等）在列出任务时作为每个部分的标题可用。
> 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 选项在任务列表中获取更多信息。
$ gradle tasks --all
--no-all 选项可以将报告限制为分配给任务组的任务。
如果您需要更精确，可以使用 --group 选项仅显示特定组的任务。
$ gradle tasks --group="build setup"
显示任务使用详细信息
运行 gradle help --task someTask 会显示有关特定任务的详细信息。
$ gradle -q help --task libs
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` 选项调用它们。
$ gradle myTask --scan
这将为您提供一个指向基于 Web 的报告的链接，您可以在其中找到 依赖项信息，例如：
列出项目依赖项
运行 `dependencies` 任务会为您提供所选项目的依赖项列表，按配置细分。对于每个配置，都会以树状结构显示该配置的直接和传递依赖项。
以下是此报告的示例
$ gradle dependencies
> 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` 任务会可视化所选项目的构建脚本依赖项，类似于 `gradle dependencies` 如何可视化正在构建的软件的依赖项。
$ gradle buildEnvironment
运行 `dependencyInsight` 任务会让您深入了解与指定输入匹配的特定依赖项（或依赖项）。
$ gradle dependencyInsight --dependency [...] --configuration [...]
`--configuration` 参数将报告限制为特定配置，例如 `compileClasspath`。
列出项目属性
运行 `properties` 任务会为您提供所选项目的属性列表。
$ gradle -q api:properties
------------------------------------------------------------ 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` 参数查询单个属性。
$ gradle -q api:properties --property allprojects
------------------------------------------------------------ Project ':api' - The shared API for the application ------------------------------------------------------------ allprojects: [project ':api']
命令行完成
Gradle 通过 gradle-completion（单独安装）为任务、选项和 Gradle 属性提供 `bash` 和 `zsh` 选项卡完成支持。
调试选项
- `-?`, `-h`, `--help`
-
显示包含内置 CLI 选项的帮助消息。要显示项目上下文选项，包括有关特定任务的帮助，请参见 `help` 任务。
- `-v`, `--version`
-
打印 Gradle、Groovy、Ant、JVM 和操作系统版本信息，并在不执行任何任务的情况下退出。
- `-V`, `--show-version`
-
打印 Gradle、Groovy、Ant、JVM 和操作系统版本信息，并继续执行指定的任务。
- `-S`, `--full-stacktrace`
-
打印任何异常的完整（非常详细）堆栈跟踪。另请参见 日志记录选项。
- `-s`, `--stacktrace`
-
打印堆栈跟踪，包括用户异常（例如编译错误）。另请参见 日志记录选项。
--scan-
创建 构建扫描，其中包含有关 Gradle 构建所有方面的详细信息。
-Dorg.gradle.debug=true-
调试 Gradle 守护进程。默认情况下，Gradle 会等待您在
localhost:5005上附加调试器。 -Dorg.gradle.debug.host=(主机地址)-
指定在启用调试时监听或连接到的主机地址。在 Java 9 及更高版本上的服务器模式下，将
*传递给主机将使服务器监听所有网络接口。默认情况下，不会将主机地址传递给 JDWP，因此在 Java 9 及更高版本上，将使用环回地址，而早期版本则监听所有接口。 -Dorg.gradle.debug.port=(端口号)-
指定在启用调试时监听的端口号。默认值为
5005。 -Dorg.gradle.debug.server=(true,false)-
如果设置为
true并且启用了调试，Gradle 将使用调试器的套接字附加模式运行构建。否则，将使用套接字监听模式。默认值为true。 -Dorg.gradle.debug.suspend=(true,false)-
如果设置为
true并且启用了调试，运行 Gradle 的 JVM 将暂停，直到附加调试器。默认值为true。 -Dorg.gradle.daemon.debug=true-
调试 Gradle 守护进程。（与
-Dorg.gradle.debug重复）
性能选项
在优化和 改进 构建性能时，请尝试使用这些选项。
这些选项中的许多可以在 指定 在 gradle.properties 文件中，因此命令行标志是不必要的。
--build-cache,--no-build-cache-
切换 Gradle 构建缓存。Gradle 将尝试重用以前构建的输出。默认情况下关闭。
--configuration-cache,--no-configuration-cache-
切换 配置缓存。Gradle 将尝试重用以前构建的构建配置。默认情况下关闭。
--configuration-cache-problems=(fail,warn)-
配置配置缓存如何处理问题。默认值为
fail。设置为
warn以报告问题，但不失败构建。设置为
fail以报告问题，如果存在任何问题，则失败构建。 --configure-on-demand,--no-configure-on-demand-
切换按需配置。仅在本次构建运行中配置相关项目。默认关闭。
--max-workers-
设置 Gradle 可使用的最大工作线程数。默认值为处理器数量。
--parallel,--no-parallel-
并行构建项目。有关此选项的限制，请参阅 并行项目执行。默认关闭。
--priority-
指定 Gradle 守护进程及其启动的所有进程的调度优先级。值为
normal或low。默认值为 normal。 --profile-
在
layout.buildDirectory.dir("reports/profile")目录中生成高级性能报告。建议使用--scan。 --scan-
生成包含详细性能诊断的构建扫描。
--watch-fs,--no-watch-fs-
切换 文件系统监视。启用后，Gradle 会在构建之间重用其收集的有关文件系统的信息。在 Gradle 支持此功能的操作系统上默认启用。
Gradle 守护进程选项
您可以通过以下命令行选项管理 Gradle 守护进程。
--daemon,--no-daemon-
使用 Gradle 守护进程 运行构建。如果守护进程未运行或现有守护进程繁忙，则启动守护进程。默认开启。
--foreground-
在前景进程中启动 Gradle 守护进程。
--status(独立命令)-
运行
gradle --status列出正在运行和最近停止的 Gradle 守护进程。它只显示相同 Gradle 版本的守护进程。 --stop(独立命令)-
运行
gradle --stop停止所有相同版本的 Gradle 守护进程。 -Dorg.gradle.daemon.idletimeout=(毫秒数)-
Gradle 守护进程将在空闲此毫秒数后自行停止。默认值为 10800000 (3 小时)。
日志记录选项
设置日志级别
您可以使用以下选项自定义 Gradle 日志记录的 详细程度，从最不详细到最详细排序。
-Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug)-
通过 Gradle 属性设置日志级别。
-q,--quiet-
仅记录错误。
-w,--warn-
将日志级别设置为警告。
-i,--info-
将日志级别设置为信息。
-d,--debug-
以调试模式记录日志（包括正常的堆栈跟踪）。
Lifecycle 是默认的日志级别。
自定义日志格式
您可以通过以下方式指定控制台模式来控制丰富输出（颜色和字体变体）的使用
-Dorg.gradle.console=(auto,plain,rich,verbose)-
通过 Gradle 属性指定控制台模式。不同模式的描述如下。
--console=(auto,plain,rich,verbose)-
指定要生成的控制台输出类型。
设置为
plain以仅生成纯文本。此选项禁用控制台输出中的所有颜色和其他丰富输出。当 Gradle 未附加到终端时，这是默认设置。设置为
auto（默认值）以在构建过程附加到控制台时在控制台输出中启用颜色和其他丰富输出，或者在未附加到控制台时仅生成纯文本。当 Gradle 附加到终端时，这是默认设置。设置为
rich以在控制台输出中启用颜色和其他丰富输出，无论构建过程是否未附加到控制台。当未附加到控制台时，构建输出将使用 ANSI 控制字符来生成丰富输出。设置为
verbose以启用颜色和其他丰富输出，如rich，并在生命周期日志级别输出任务名称和结果（与 Gradle 3.5 及更早版本中的默认行为相同）。
显示或隐藏警告
默认情况下，Gradle 不会显示所有警告（例如弃用警告）。相反，Gradle 会收集它们并在构建结束时呈现摘要，例如
Deprecated Gradle features were used in this build, making it incompatible with Gradle 5.0.
您可以使用以下选项控制控制台上警告的详细程度
-Dorg.gradle.warning.mode=(all,fail,none,summary)-
通过 Gradle 属性 指定警告模式。不同模式的描述如下。
--warning-mode=(all,fail,none,summary)-
指定如何记录警告。默认值为
summary。设置为
all以记录所有警告。设置为
fail以记录所有警告，如果存在任何警告，则使构建失败。设置为
summary以抑制所有警告并在构建结束时记录摘要。设置为
none以抑制所有警告，包括构建结束时的摘要。
执行选项
以下选项通过更改构建内容或依赖项解析方式来影响构建的执行方式。
--include-build-
将构建作为 复合构建 运行，包括指定的构建。
--offline-
指定构建应 不访问网络资源 进行操作。
-U,--refresh-dependencies-
刷新 依赖项状态。
--continue-m,--dry-run-
以禁用所有任务操作的方式运行 Gradle。使用此选项显示将要执行的任务。
-t,--continuous-
启用 持续构建。Gradle 不会退出，并且当任务文件输入发生更改时会重新执行任务。
--write-locks-
指示所有已解析的且可锁定配置应将其 锁定状态 持久化。
--update-locks <group:name>[,<group:name>]*-
指示必须在 锁定文件 中更新指定模块的版本。
此标志也暗示
--write-locks。 -a,--no-rebuild-
不要重建项目依赖项。这对 调试和微调
buildSrc有用，但可能会导致错误的结果。谨慎使用！
环境选项
您可以自定义构建脚本、设置、缓存等方面的许多内容，方法是使用以下选项。
-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-
指定 Gradle 的起始目录。默认为当前目录。
--project-cache-dir-
指定特定于项目的缓存目录。默认值为根项目目录中的
.gradle。 -D,--system-prop-
设置 JVM 的系统属性，例如
-Dmyprop=myvalue。 -I,--init-script-
指定初始化脚本。
-P,--project-prop-
设置根项目的项目属性，例如
-Pmyprop=myvalue。 -Dorg.gradle.jvmargs-
设置 JVM 参数。
-Dorg.gradle.java.home-
设置 JDK 主目录。
任务选项
任务可以定义特定于任务的选项，这些选项与上面各节中描述的大多数全局选项不同（这些选项由 Gradle 本身解释，可以出现在命令行中的任何位置，并且可以使用--help选项列出）。
任务选项
-
由任务本身使用和解释；
-
必须在命令行中紧跟在任务之后指定；
-
可以使用
gradle help --task someTask列出（请参阅显示任务使用详细信息）。
要了解如何为自己的任务声明命令行选项，请参阅声明和使用命令行选项。
引导新项目
创建新的 Gradle 构建
使用内置的 gradle init 任务来创建新的 Gradle 构建，包含新的或现有的项目。
$ gradle init
大多数情况下，会指定项目类型。可用的类型包括 basic（默认）、java-library、java-application 等等。有关详细信息，请参阅 init 插件文档。
$ gradle init --type java-library
标准化和配置 Gradle
内置的 gradle wrapper 任务会生成一个脚本 gradlew，该脚本会调用声明的 Gradle 版本，并在必要时事先下载它。
$ gradle wrapper --gradle-version=8.1
除了 --gradle-version 之外，还可以指定 --distribution-type=(bin|all)、--gradle-distribution-url、--gradle-distribution-sha256-sum。
有关使用这些选项的完整详细信息，请参阅 Gradle wrapper 部分。
持续构建
持续构建允许您在文件输入发生更改时自动重新执行请求的任务。您可以使用 -t 或 --continuous 命令行选项以这种模式执行构建。
例如，您可以通过运行以下命令来持续运行 test 任务及其所有依赖任务：
$ gradle test --continuous
当源代码或测试文件发生更改时，Gradle 的行为就像您运行了 gradle test 一样。这意味着无关的更改（例如对构建脚本的更改）不会触发重建。要合并构建逻辑更改，必须手动重新启动持续构建。
持续构建使用 文件系统监视 来检测对输入的更改。如果文件系统监视在您的系统上不起作用，那么持续构建也无法正常工作。特别是，在使用 --no-daemon 时，持续构建不起作用。
当 Gradle 检测到对输入的更改时，它不会立即触发构建。相反，它会等待一段时间（静默期），直到不再检测到其他更改。您可以通过 Gradle 属性 org.gradle.continuous.quietperiod 以毫秒为单位配置静默期。
终止持续构建
如果 Gradle 连接到交互式输入源（例如终端），则可以通过按 CTRL-D 退出持续构建（在 Microsoft Windows 上，需要在 CTRL-D 后按 ENTER 或 RETURN）。
如果 Gradle 未连接到交互式输入源（例如，作为脚本的一部分运行），则必须终止构建过程（例如，使用 kill 命令或类似命令）。
如果构建是通过 Tooling API 执行的，则可以使用 Tooling API 的取消机制取消构建。
在 continuous_builds.html 持续构建中了解更多信息。
符号链接的更改
通常，Gradle 不会检测到符号链接或通过符号链接引用的文件的更改。
构建逻辑的更改不被考虑
当前实现不会在后续构建中重新计算构建模型。这意味着对任务配置或对构建模型的任何其他更改实际上会被忽略。