命令列介面是與 Gradle 互動的主要方法。
以下是執行和自訂 Gradle 命令列的參考。它也可用於編寫腳本或配置持續整合時的參考。
強烈建議使用Gradle Wrapper。在以下範例中，以 ./gradlew (在 macOS / Linux 中) 或 gradlew.bat (在 Windows 中) 替換 gradle。
在命令列上執行 Gradle 符合以下結構
gradle [taskName...] [--option-name...]
選項允許在 task 名稱之前和之後。
gradle [--option-name...] [taskName...]
如果指定了多個 task，您應該用空格分隔它們。
gradle [taskName1 taskName2...] [--option-name...]
接受值的選項可以使用或不使用 = 分隔選項和引數。建議使用 =。
gradle [...] --console=plain
啟用行為的選項具有長格式選項，其反向選項以 --no- 指定。以下是相反的選項。
gradle [...] --build-cache gradle [...] --no-build-cache
許多長格式選項都有短選項等效項。以下是等效的選項
gradle --help gradle -h
許多命令列標記可以在 gradle.properties 中指定，以避免需要輸入。請參閱配置建置環境指南以了解詳細資訊。 |
命令列用法
以下章節說明 Gradle 命令列介面的使用方式。
執行 task
您可以在專案報告章節中了解可用的專案和 task。
大多數建置都支援一組常見的 task，稱為生命週期 task。這些包括 build、assemble 和 check task。
若要在根專案上執行名為 myTask 的 task，請輸入
$ gradle :myTask
這將執行單個 myTask 及其所有相依性。
為 task 指定選項
若要將選項傳遞給 task，請在 task 名稱後面的選項名稱加上 -- 前綴
$ gradle exampleTask --exampleOption=exampleValue
區分 task 選項與內建選項
Gradle 不會阻止 task 註冊與 Gradle 內建選項衝突的選項，例如 --profile 或 --help。
您可以使用命令中 task 名稱之前的 -- 分隔符來修正與 Gradle 內建選項衝突的 task 選項
$ gradle [--built-in-option-name...] -- [taskName...] [--task-option-name...]
考慮一個名為 mytask 的 task，它接受一個名為 profile 的選項
-
在
gradle mytask --profile中，Gradle 將--profile視為內建的 Gradle 選項。 -
在
gradle -- mytask --profile=value中，Gradle 將--profile作為 task 選項傳遞。
在多專案建置中執行 task
在多專案建置中，可以使用 : 分隔子專案名稱和 task 名稱來執行子專案 task。從根專案執行時，以下是等效的
$ gradle :subproject:taskName
$ gradle subproject:taskName
您也可以使用僅由 task 名稱組成的 task 選擇器來為所有子專案執行 task。
當從根專案目錄調用時，以下命令會為所有子專案執行 test task
$ gradle test
某些 task 選擇器，例如 help 或 dependencies，只會在調用它們的專案上執行 task，而不會在所有子專案上執行。 |
當從子專案內調用 Gradle 時，應省略專案名稱
$ cd subproject
$ gradle taskName
當從子專案目錄執行 Gradle Wrapper 時，請相對地參考 gradlew。例如：../gradlew taskName。 |
執行多個 task
您也可以指定多個 task。task 的相依性決定了確切的執行順序，並且沒有相依性的 task 可能會比它在命令列上列出的順序更早執行。
例如，以下命令將按照它們在命令列上列出的順序執行 test 和 deploy task，並且還將執行每個 task 的相依性。
$ gradle test deploy
命令列順序安全
雖然 Gradle 將始終嘗試快速執行建置，但命令列順序安全也會受到尊重。
例如，以下命令將執行 clean 和 build 以及它們的相依性
$ gradle clean build
但是，命令列順序中暗示的意圖是 clean 應該先執行，然後再執行 build。即使這樣做會使建置執行得更快，但在 build 之後執行 clean 是不正確的，因為 clean 會移除 build 建立的內容。
相反地，如果命令列順序是 build 後面跟著 clean，則在 build 之前執行 clean 是不正確的。雖然 Gradle 將盡可能快速地執行建置，但它也會尊重命令列上指定的 task 順序的安全性，並確保當以該順序指定時，clean 在 build 之前執行。
請注意，命令列順序安全依賴於 task 正確宣告它們建立、使用或移除的內容。
從執行中排除 task
您可以使用 -x 或 --exclude-task 命令列選項並提供要排除的 task 名稱來排除 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 task 沒有執行，即使 dist task 依賴於它。test task 的相依性，例如 compileTest，也不會執行。其他 task 依賴的 test 的相依性，例如 compile，仍然會執行。
強制 task 執行
您可以使用 --rerun-tasks 選項強制 Gradle 執行所有 task，忽略最新檢查
$ gradle test --rerun-tasks
這將強制執行 test 和 test 的所有 task 相依性。它類似於執行 gradle clean test，但不會刪除建置產生的輸出。
或者，您可以使用 --rerun 內建task 選項告訴 Gradle 重新執行特定的 task。
在 task 失敗後繼續建置
預設情況下，當任何 task 失敗時，Gradle 會中止執行並使建置失敗。這允許建置更快完成，並防止級聯失敗混淆錯誤的根本原因。
您可以使用 --continue 選項強制 Gradle 在發生失敗時執行每個 task
$ gradle test --continue
當使用 --continue 執行時，如果該 task 的所有相依性都已完成且沒有失敗，則 Gradle 會執行建置中的每個 task。
例如，如果受測程式碼中存在編譯錯誤，則測試不會運行，因為 test task 依賴於 compilation task。Gradle 會在建置結束時輸出每個遇到的失敗。
如果任何測試失敗，許多測試套件都會使整個 test task 失敗。程式碼覆蓋率和報告工具通常在測試 task 之後運行，因此「快速失敗」行為可能會在這些工具運行之前停止執行。 |
名稱縮寫
當您在命令列上指定 task 時，您不必提供 task 的完整名稱。您可以提供足夠的 task 名稱來唯一識別 task。例如，gradle che 很可能足以讓 Gradle 識別 check task。
專案名稱也適用相同規則。您可以使用 gradle lib:che 命令在 library 子專案中執行 check task。
更具體地說，您可以使用命令 gradle mAL:cT 在 my-awesome-library 子專案中執行 compileTest task。
$ gradle mAL:cT
> Task :my-awesome-library:compileTest compiling unit tests BUILD SUCCESSFUL in 0s 1 actionable task: 1 executed
縮寫也可以與 -x 命令列選項一起使用。
追蹤名稱擴展
對於複雜的專案，如果執行的 task 是預期的 task，可能會模稜兩可。當使用縮寫名稱時，一個小小的錯字可能會導致執行意外的 task。
當啟用 INFO 或更詳細的記錄時，輸出將包含關於專案和 task 名稱擴展的額外資訊。
例如，當在前一個範例中執行 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'.
常用 task
以下是內建和大多數主要 Gradle 外掛程式套用的 task 慣例。
專案報告
Gradle 提供了幾個內建 task，用於顯示您建置的特定詳細資訊。這對於了解您建置的結構和相依性，以及偵錯問題非常有用。
列出 task
執行 gradle tasks 會提供您所選專案的主要 task 列表。此報告會顯示專案的預設 task (如果有的話)，以及每個 task 的描述
$ gradle tasks
預設情況下，此報告僅顯示分配給 task 群組的 task。
群組 (例如驗證、發布、幫助、建置…) 在列出 task 時可用作每個區段的標頭
> 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 選項在 task 列表中取得更多資訊
$ gradle tasks --all
--no-all 選項可以將報告限制為分配給 task 群組的 task。
如果您需要更精確，您可以使用 --group 選項僅顯示來自特定群組的 task
$ gradle tasks --group="build setup"
顯示 task 用法詳細資訊
執行 gradle help --task someTask 會提供您關於特定 task 的詳細資訊
$ 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
此資訊包括完整的 task 路徑、task 類型、可能的task 專用命令列選項，以及給定 task 的描述。
您可以使用 --types 選項取得關於 task 類別類型的詳細資訊，或使用 --no-types 隱藏此資訊。
報告相依性
Build Scan 提供關於哪些配置上存在哪些相依性、傳遞相依性和相依性版本選擇的完整視覺報告。它們可以使用 --scan 選項調用
$ gradle myTask --scan
這將為您提供一個指向基於 Web 的報告的連結，您可以在其中找到像這樣的相依性資訊
列出專案相依性
執行 dependencies task 會提供您所選專案的相依性列表，按配置細分。對於每個配置，該配置的直接和傳遞相依性都以樹狀結構顯示。
以下是此報告的範例
$ 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 task 會視覺化所選專案的建置腳本相依性，類似於 gradle dependencies 如何視覺化正在建置的軟體的相依性
$ gradle buildEnvironment
執行 dependencyInsight task 會讓您深入了解與指定輸入匹配的特定相依性 (或多個相依性)
$ gradle dependencyInsight --dependency [...] --configuration [...]
--configuration 參數將報告限制為特定配置，例如 compileClasspath。
列出專案屬性
執行 properties task 會提供您所選專案的屬性列表
$ 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 (單獨安裝) 為 task、選項和 Gradle 屬性提供 bash 和 zsh 標籤自動完成支援
偵錯選項
-?、-h、--help-
顯示包含內建 CLI 選項的說明訊息。若要顯示專案上下文選項，包括關於特定 task 的說明，請參閱
helptask。 -v、--version-
列印 Gradle、Groovy、Ant、Launcher & Daemon JVM 和作業系統版本資訊，並在不執行任何 task 的情況下結束。
-V、--show-version-
列印 Gradle、Groovy、Ant、Launcher & Daemon JVM 和作業系統版本資訊，並繼續執行指定的 task。
-S、--full-stacktrace-
針對任何例外狀況列印完整 (非常詳細) 的堆疊追蹤。另請參閱記錄選項。
-s、--stacktrace-
也針對使用者例外狀況 (例如編譯錯誤) 列印堆疊追蹤。另請參閱記錄選項。
--scan-
建立Build Scan，其中包含關於您的 Gradle 建置所有方面的細緻資訊。
-Dorg.gradle.debug=true-
一個Gradle 屬性，用於偵錯Gradle Daemon 程序。Gradle 將等待您預設在
localhost:5005連接偵錯器。 -Dorg.gradle.debug.host=(host address)-
一個Gradle 屬性，用於指定在啟用偵錯時要監聽或連接的主機位址。在 Java 9 及更高版本上的伺服器模式中，為主機傳遞
*將使伺服器監聽所有網路介面。預設情況下，沒有主機位址傳遞給 JDWP，因此在 Java 9 及更高版本上，使用迴路位址，而較早的版本監聽所有介面。 -Dorg.gradle.debug.port=(port number)-
一個Gradle 屬性，用於指定在啟用偵錯時要監聽的埠號。預設值為
5005。 -Dorg.gradle.debug.server=(true,false)-
一個Gradle 屬性，如果設定為
true且啟用偵錯，將導致 Gradle 以偵錯器的 socket-attach 模式執行建置。否則，將使用 socket-listen 模式。預設值為true。 -Dorg.gradle.debug.suspend=(true,false)-
一個Gradle 屬性，如果設定為
true且啟用偵錯，則執行 Gradle 的 JVM 將暫停，直到連接偵錯器為止。預設值為true。 -Dorg.gradle.daemon.debug=true-
一個Gradle 屬性，用於偵錯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 daemon 選項
您可以透過以下命令列選項管理Gradle Daemon。
--daemon、--no-daemon-
使用Gradle Daemon 執行建置。如果 Daemon 未執行或現有 Daemon 忙碌，則啟動 Daemon。預設為開啟。
--foreground-
在前景程序中啟動 Gradle Daemon。
--status(獨立命令)-
執行
gradle --status以列出正在執行和最近停止的 Gradle Daemon。它僅顯示相同 Gradle 版本的 Daemon。 --stop(獨立命令)-
執行
gradle --stop以停止所有相同版本的 Gradle Daemon。 -Dorg.gradle.daemon.idletimeout=(number of milliseconds)-
一個Gradle 屬性，其中 Gradle Daemon 將在此閒置時間 (以毫秒為單位) 後自行停止。預設值為 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 及更早版本中的預設行為）。
回報問題
--no-problems-report-
停用產生
build/reports/problems-report.html，預設情況下，此報告會根據提供給 Problems API 的問題產生。 --problems-report-
啟用產生
build/reports/problems-report.html。這是預設行為。報告會根據提供給 Problems API 的問題產生。
顯示或隱藏警告
預設情況下，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 引數的 Gradle 屬性。
-Dorg.gradle.java.home-
設定 JDK 主目錄的 Gradle 屬性。
任務選項
任務可以定義特定於任務的選項，這些選項與上述章節中描述的大多數全域選項不同 (全域選項由 Gradle 本身解釋，可以出現在命令列中的任何位置，並且可以使用 --help 選項列出)。
Task 選項
-
由任務本身消耗和解釋；
-
必須在命令列中的任務之後立即指定；
-
可以使用
gradle help --task someTask列出 (請參閱 顯示任務用法詳細資訊)。
若要了解如何為您自己的任務宣告命令列選項，請參閱 宣告和使用命令列選項。
內建任務選項
內建任務選項是所有任務都可作為任務選項使用的選項。目前，存在以下內建任務選項
--rerun-
即使任務為最新狀態，也導致重新執行任務。類似於
--rerun-tasks，但適用於特定任務。
啟動新專案
建立新的 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 章節中。