命令行界面是与 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。clean 在 after 执行是不正确的build，即使这样做会导致构建执行得更快，因为clean会删除build创建的内容。
相反，如果命令行命令后面跟着build，则在 之前clean执行是不正确的。尽管 Gradle 会尽快执行构建，但它也会尊重命令行上指定的任务顺序的安全性，并确保在按该顺序指定的任务之前运行。cleanbuildcleanbuild
请注意，命令行顺序安全依赖于任务正确声明它们创建、使用或删除的内容。
从执行中排除任务
您可以使用-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，仍然会执行。
强制执行任务
您可以使用以下选项强制 Gradle 执行所有任务，忽略最新检查--rerun-tasks：
$ gradle test --rerun-tasks
这将强制test执行所有任务依赖项。test它类似于 running gradle clean test，但不会删除构建生成的输出。
--rerun或者，您可以使用内置任务选项告诉 Gradle 重新运行特定任务。
任务失败后继续构建
默认情况下，当任何任务失败时，Gradle 都会中止执行并导致构建失败。这使得构建能够更快地完成，并防止级联失败混淆错误的根本原因。
您可以使用该--continue选项强制 Gradle 在发生故障时执行每个任务：
$ gradle test --continue
当使用 执行时--continue，Gradle 会执行构建中的每个任务，前提是该任务的所有依赖项都已顺利完成。
例如，如果被测代码中存在编译错误，则测试不会运行，因为任务test依赖于compilation任务。 Gradle 在构建结束时输出遇到的每个失败。
如果任何测试失败，许多测试套件就会导致整个test任务失败。代码覆盖率和报告工具经常在测试任务之后运行，因此“快速失败”行为可能会在这些工具运行之前停止执行。
|
名称缩写
当您在命令行上指定任务时，不必提供任务的全名。您可以提供足够的任务名称来唯一标识该任务。例如，gradle cheGradle 识别check任务可能就足够了。
这同样适用于项目名称。您可以使用命令执行子项目check中的任务。librarygradle lib:che
更具体地说，您可以使用命令运行子项目compileTest中的任务。my-awesome-librarygradle mAL:cT
$ 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 属性提供 tab 补全支持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 Daemon进程。
localhost:5005默认情况下，Gradle 将等待您附加调试器。 -Dorg.gradle.debug.host=(host address)-
指定启用调试时要侦听或连接的主机地址。在 Java 9 及更高版本的服务器模式中，传递
*主机将使服务器侦听所有网络接口。默认情况下，没有主机地址传递给 JDWP，因此在 Java 9 及更高版本上，使用环回地址，而早期版本则侦听所有接口。 -Dorg.gradle.debug.port=(port number)-
指定启用调试时侦听的端口号。默认为
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 Daemon进程。 （重复
-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。默认为正常。 --profile-
在目录中生成高级性能报告
layout.buildDirectory.dir("reports/profile")。--scan是优选的。 --scan-
生成包含详细性能诊断的构建扫描。
--watch-fs,--no-watch-fs-
切换监视文件系统。启用后，Gradle 会在构建之间重用其收集的有关文件系统的信息。 在 Gradle 支持此功能的操作系统上默认启用。
Gradle 守护进程选项
您可以通过以下命令行选项管理Gradle Daemon 。
--daemon,--no-daemon-
使用Gradle Daemon来运行构建。如果守护程序未运行或现有守护程序正忙，则启动该守护程序。默认为打开。
--foreground-
在前台进程中启动 Gradle 守护进程。
--status（独立命令）-
运行
gradle --status以列出正在运行和最近停止的 Gradle 守护进程。它仅显示相同 Gradle 版本的守护进程。 --stop（独立命令）-
运行
gradle --stop以停止同一版本的所有 Gradle 守护进程。 -Dorg.gradle.daemon.idletimeout=(number of milliseconds)-
Gradle Daemon 将在空闲时间达到该毫秒数后自行停止。默认值为 10800000（3 小时）。
记录选项
设置日志级别
您可以使用以下选项自定义 Gradle 日志记录的详细程度，按从最详细到最详细的顺序排列。
-Dorg.gradle.logging.level=(quiet,warn,lifecycle,info,debug)-
通过 Gradle 属性设置日志记录级别。
-q,--quiet-
仅记录错误。
-w,--warn-
将日志级别设置为警告。
-i,--info-
将日志级别设置为信息。
-d,--debug-
登录调试模式（包括正常的堆栈跟踪）。
生命周期是默认的日志级别。
自定义日志格式
您可以通过以下方式指定控制台模式来控制丰富输出（颜色和字体变体）的使用：
-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抑制所有警告，包括构建结束时的摘要。
丰富的控制台
Gradle 丰富的控制台会在构建运行时显示额外的信息。
特征：
-
进度条和计时器直观地描述了整体状态
-
下面的并行进行中工作线描述了现在正在发生的事情
-
颜色和字体用于突出显示重要的输出和错误
执行选项
以下选项通过更改构建内容或解决依赖关系的方式来影响构建的执行方式。
--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
除了 之外，您还可以指定--distribution-type=(bin|all), --gradle-distribution-url。
有关使用这些选项的完整详细信息记录在Gradle 包装器部分中。--gradle-distribution-sha256-sum--gradle-version
持续构建
持续构建允许您在文件输入更改时自动重新执行请求的任务。您可以使用-t或--continuous命令行选项在此模式下执行构建。
例如，您可以test通过运行以下命令连续运行该任务和所有相关任务：
$ gradle test --continuous
gradle testGradle 的行为就像您在更改有助于请求任务的源或测试后运行一样。这意味着不相关的更改（例如对构建脚本的更改）将不会触发重建。要合并构建逻辑更改，必须手动重新启动连续构建。
持续构建使用文件系统监视来检测输入的更改。如果文件系统监视在您的系统上不起作用，那么连续构建也将不起作用。特别是，使用时连续构建不起作用--no-daemon。
当 Gradle 检测到输入发生更改时，它不会立即触发构建。相反，它将等待一段时间（安静期），直到没有检测到任何其他更改。您可以通过 Gradle 属性以毫秒为单位配置安静期org.gradle.continuous.quietperiod。
终止持续构建
如果 Gradle 连接到交互式输入源（例如终端），则可以通过按退出连续构建CTRL-D（在 Microsoft Windows 上，还需要按ENTER或RETURN之后CTRL-D）。
如果 Gradle 未附加到交互式输入源（例如作为脚本的一部分运行），则必须终止构建过程（例如使用命令kill或类似命令）。
如果通过 Tooling API 执行构建，则可以使用 Tooling API 的取消机制取消构建。
在Continuous_builds.html持续构建中了解更多信息。
符号链接的更改
一般来说，Gradle 不会检测符号链接或通过符号链接引用的文件的更改。
不考虑构建逻辑的更改
当前的实现不会在后续构建中重新计算构建模型。这意味着对任务配置的更改或对构建模型的任何其他更改都将被有效忽略。