以下是一些常見問題以及解決方案的集合。您可以取得其他提示，並搜尋 Gradle 論壇和 StackOverflow #gradle 答案。

安裝疑難排解

如果您已遵循安裝指示，但無法執行您的 Gradle 建置，以下是一些可能有幫助的提示。

如果您在調用 Gradle Wrapper 之外安裝了 Gradle，您可以透過在終端機中執行 gradle --version 來檢查您的 Gradle 安裝。

您應該會看到類似這樣的內容

❯ gradle --version

------------------------------------------------------------
Gradle {gradleVersion}
------------------------------------------------------------

Build time:            2024-06-17 18:10:00 UTC
Revision:              6028379bb5a8512d0b2c1be6403543b79825ef08

Kotlin:        1.9.23
Groovy:        3.0.21
Ant:           Apache Ant(TM) version 1.10.13 compiled on January 4 2023
Launcher JVM:  11.0.23 (Eclipse Adoptium 11.0.23+9)
Daemon JVM:    /Library/Java/JavaVirtualMachines/temurin-11.jdk/Contents/Home (no JDK specified, using current Java home)
OS:            Mac OS X 14.5 aarch64

如果沒有，以下是您可能會看到的其他情況。

找不到命令：gradle

如果您收到「command not found: gradle」，您必須確保 Gradle 已正確新增至您的 PATH。

JAVA_HOME 設定為無效目錄

如果您收到類似這樣的錯誤

ERROR: JAVA_HOME is set to an invalid directory

將您環境中的 JAVA_HOME 變數設定為與您的 Java 安裝位置相符

$ export JAVA_HOME=/Users/user/Library/Java/JavaVirtualMachines/corretto-11.0.22/Contents/Home
$ echo $JAVA_HOME
/Users/user/Library/Java/JavaVirtualMachines/corretto-11.0.22/Contents/Home

您必須確保已正確安裝 Java Development Kit 版本 8 或更高版本，並且已設定 JAVA_HOME 環境變數，且 Java 已新增至您的 PATH。

權限遭拒

如果您收到「permission denied」，表示 Gradle 可能存在於正確的位置，但它不可執行。您可以使用 chmod +x path/to/executable 在 *nix 系統上修正此問題。

其他安裝失敗

如果 gradle —-version 運作正常，但您的所有建置都以相同的錯誤失敗，則可能是您的其中一個 Gradle 建置配置腳本已損壞。

您可以執行 gradle help 來驗證 Gradle 腳本的問題，這會執行配置腳本，但不執行 Gradle 工作。如果錯誤持續存在，則表示建置配置有問題。如果沒有，則問題存在於執行一個或多個請求的工作時（Gradle 會先執行配置腳本，然後執行建置步驟）。

除錯依賴解析

常見的依賴解析問題，例如解決版本衝突，已在疑難排解依賴解析中涵蓋。

您可以查看依賴樹，並查看哪些已解析的依賴版本與請求的版本不同，方法是按一下Dependencies 檢視並使用搜尋功能，指定解析原因。

troubleshooting dependency management build scan
圖 1. 使用建置掃描除錯依賴衝突

具有篩選條件的實際建置掃描可用於探索。

疑難排解建置緩慢問題

如需建置效能問題（包括「同步時間緩慢」），請參閱提升 Gradle 建置的效能。

Android 開發人員應觀看 Android SDK 工具團隊關於加速您的 Android Gradle 建置的簡報。Android Studio 使用者指南關於最佳化建置速度中也涵蓋了許多提示。

除錯建置邏輯

將除錯器附加至您的建置

您可以設定中斷點並在您的 Gradle 建置本身中除錯 buildSrc 和獨立外掛，方法是將 org.gradle.debug 屬性設定為「true」，然後將遠端除錯器附加至埠 5005。您可以透過將 org.gradle.debug.port 屬性設定為所需的埠號碼來變更埠號碼。

若要透過網路遠端附加除錯器，您必須將 org.gradle.debug.host 屬性設定為機器的 IP 位址或 *（監聽所有介面）。

❯ gradle help -Dorg.gradle.debug=true

使用 Kotlin DSL，您可以除錯建置腳本本身。

以下影片示範如何使用 IntelliJ IDEA 除錯範例建置。

remote debug gradle
圖 2. 建置腳本的互動式除錯

新增和變更記錄

除了控制記錄詳細程度之外，您還可以透過使用--console=verbose 旗標來控制生命週期記錄中工作結果（例如「UP-TO-DATE」）的顯示。

您也可以透過註冊各種事件監聽器來取代 Gradle 的大部分記錄。在記錄文件中說明了一個自訂事件記錄器範例。您也可以從外部工具控制記錄，使其更詳細以除錯其執行。

來自 Gradle Daemon 的其他記錄可以在 $GRADLE_USER_HOME/daemon/8.13/ 下找到。

工作在應該為 UP-TO-DATE 時執行

--info 記錄說明了工作為何執行，儘管建置掃描透過前往 Timeline 檢視並按一下您要檢查的工作，以可搜尋的視覺化方式執行此操作。

troubleshooting task execution build scan
圖 3. 使用建置掃描除錯增量建置

您可以從此列表了解工作結果的含義。

除錯 IDE 整合

IDE 內許多不常見的錯誤可以透過「重新整理」Gradle 來解決。另請參閱關於在 IntelliJ IDEA 和 Eclipse 中使用 Gradle 的更多文件。

重新整理 IntelliJ IDEA

這僅適用於連結到 IntelliJ 的 Gradle 專案。

從主選單中，前往 View > Tool Windows > Gradle。然後按一下Refresh 圖示。

troubleshooting refresh intellij
圖 4. 在 IntelliJ IDEA 中重新整理 Gradle 專案

重新整理 Eclipse（使用 Buildship）

如果您使用 Buildship 作為 Eclipse IDE，您可以透過開啟「Gradle Tasks」檢視並按一下「Refresh」圖示，或在編輯 Gradle 腳本時從上下文選單執行 Gradle > Refresh Gradle Project 命令，來重新同步您的 Gradle 建置。

troubleshooting refresh eclipse
圖 5. 在 Eclipse Buildship 中重新整理 Gradle 專案

疑難排解 daemon 連線問題

如果您的 Gradle 建置在執行任何工作之前失敗，您可能遇到網路配置問題。當 Gradle 無法與 Gradle daemon 程序通訊時，建置將立即失敗，並顯示類似以下的訊息

$ gradle help

Starting a Gradle Daemon, 1 stopped Daemon could not be reused, use --status for details

FAILURE: Build failed with an exception.

* What went wrong:
A new daemon was started but could not be connected to: pid=DaemonInfo{pid=55913, address=[7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[/127.0.0.1]], state=Busy, ...

當使用網路位址轉譯 (NAT) 偽裝時，可能會發生這種情況。當啟用 NAT 偽裝時，應視為本機電腦的連線會被遮罩以顯示來自外部 IP 位址。Gradle 拒絕連線到任何外部 IP 位址，作為安全預防措施。

此問題的解決方案是調整您的網路配置，使本機連線不會被修改為顯示來自外部位址。

您可以在 daemon 記錄檔中監控偵測到的網路設定和連線請求 ($GRADLE_USER_HOME/daemon/<Gradle 版本>/daemon-<PID>.out.log)。

2021-08-12T12:01:50.755+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding IP addresses for network interface enp0s3
2021-08-12T12:01:50.759+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Is this a loopback interface? false
2021-08-12T12:01:50.769+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding remote address /fe80:0:0:0:85ba:3f3e:1b88:c0e1%enp0s3
2021-08-12T12:01:50.770+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding remote address /10.0.2.15
2021-08-12T12:01:50.770+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding IP addresses for network interface lo
2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Is this a loopback interface? true
2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding loopback address /0:0:0:0:0:0:0:1%lo
2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding loopback address /127.0.0.1
2021-08-12T12:01:50.775+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.TcpIncomingConnector] Listening on [7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[localhost/127.0.0.1]].
...
2021-08-12T12:01:50.797+0200 [INFO] [org.gradle.launcher.daemon.server.DaemonRegistryUpdater] Advertising the daemon address to the clients: [7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[localhost/127.0.0.1]]
...
2021-08-12T12:01:50.923+0200 [ERROR] [org.gradle.internal.remote.internal.inet.TcpIncomingConnector] Cannot accept connection from remote address /10.0.2.15.

取得額外協助

如果您在此處找不到問題的修正方法，請在協助論壇上與 Gradle 社群聯繫，或使用 help.gradle.org 搜尋相關的開發人員資源。

如果您認為您在 Gradle 中發現錯誤，請在 GitHub 上提交問題。