命令列介面是與 Gradle 互動的主要方法。
以下是執行和自訂 Gradle 命令列的參考。它也可以作為撰寫腳本或設定持續整合的參考。
強烈建議使用Gradle Wrapper。在以下範例中，將 gradle 替換為 ./gradlew（在 macOS/Linux 中）或 gradlew.bat（在 Windows 中）。
在命令列中執行 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
您可以看到，即使 dist 任務依賴於 test 任務，但 test 任務並未執行。test 任務的相依性，例如 compileTest，也未執行。依賴於 test 的其他任務相依性，例如 compile，仍然會執行。
強制執行任務
您可以使用 --rerun-tasks 選項，強制 Gradle 執行所有任務，而忽略最新檢查
$ gradle test --rerun-tasks
這將強制執行 test 和 test 的所有任務相依性。這類似於執行 gradle clean test，但不會刪除建置產生的輸出。
或者，您可以使用內建的任務選項 --rerun，告訴 Gradle 重新執行特定任務。
任務失敗後繼續建置
預設情況下，當任何任務失敗時，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
這會提供一個連結到網路報告，您可以在其中找到 依賴關係資訊，如下所示
列出專案依賴關係
執行 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-
使用 Build Scan 建立詳細資訊，了解 Gradle 建置的所有面向。
-Dorg.gradle.debug=true-
偵錯 Gradle Daemon 程序。預設情況下，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 會以偵錯器的 socket-attach 模式執行建置。否則，將使用 socket-listen 模式。預設為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 Daemon 和由其啟動的所有程序的排程優先順序。值為
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-
以偵錯模式記錄（包含正常的堆疊追蹤）。
生命週期是預設的記錄等級。
自訂記錄格式
您可以透過下列方式指定主控台模式來控制豐富輸出（顏色和字型變體）的使用
-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 偵測不到符號連結或透過符號連結參照的檔案的變更。
未考慮建置邏輯的變更
目前的實作不會在後續建置時重新計算建置模型。這表示任務組態的變更或建置模型的任何其他變更都會被忽略。