Gradle 提供工具來導覽相依性圖表並減輕 相依性地獄。使用者可以呈現相依性的完整圖表，以及找出相依性的選取原因和來源。相依性可以透過建置指令碼宣告的相依性或傳遞性相依性而產生。你可以使用下列方式視覺化相依性：

  • 內建 Gradle CLI dependencies 任務

  • 內建 Gradle CLI dependencyInsight 任務

  • 建置掃描

列出專案相依性

Gradle 提供內建 dependencies 任務來從命令列呈現相依性樹狀結構。預設情況下，相依性樹狀結構會呈現 所有組態 中的所有相依性，在 單一專案 中。相依性樹狀結構會指出每個相依性的選取版本。它也會顯示相依性衝突解決的資訊。

dependencies 任務對於傳遞性相依性相關的問題特別有幫助。你的建置檔案會列出直接相依性，但 dependencies 任務可以協助你了解在建置期間會解決哪些傳遞性相依性。

在 buildscript classpath 設定中宣告的相依性圖表可以使用 任務 buildEnvironment 來呈現。

輸出註解

dependencies 任務會以下列註解標記相依性樹狀結構

  • (*)：表示傳遞相依性子樹的重複出現。Gradle 每個專案只會展開一次傳遞相依性子樹；重複出現只會顯示子樹的根目錄，後接此註解。

  • (c)：此元素是 相依性限制，而非相依性。在樹狀結構的其他地方尋找相符的相依性。

  • (n)：無法 解析 的相依性或相依性設定。

指定相依性設定

若要專注於一個相依性設定的資訊，請提供選用參數 --configuration。就像 專案和任務名稱 一樣，Gradle 接受縮寫名稱來選擇相依性設定。例如，如果樣式與單一相依性設定相符，您可以指定 tRC 而不是 testRuntimeClasspath。下列兩個範例都顯示 Java 專案的 testRuntimeClasspath 相依性設定中的相依性

> gradle -q dependencies --configuration testRuntimeClasspath
> gradle -q dependencies --configuration tRC

若要查看專案中所有設定的清單，包括任何外掛程式所新增的設定，您可以執行 resolvableConfigurations 報告。

如需更多資訊，請參閱該外掛程式的文件 (例如，Java 外掛程式在此處 有說明)。

範例

考慮一個使用 JGit 函式庫 來執行發佈流程的來源控制管理 (SCM) 作業的專案。您可以透過 自訂相依性設定 來宣告外部工具的相依性。這可以避免污染其他內容，例如生產原始碼的編譯類別路徑。

下列範例宣告一個名為「scm」的自訂相依性設定，其中包含 JGit 相依性

build.gradle.kts
repositories {
    mavenCentral()
}

configurations {
    create("scm")
}

dependencies {
    "scm"("org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r")
}
build.gradle
repositories {
    mavenCentral()
}

configurations {
    scm
}

dependencies {
    scm 'org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r'
}

使用下列指令來檢視 scm 相依性設定的相依性樹狀結構

> gradle -q dependencies --configuration scm

------------------------------------------------------------
Root project 'dependencies-report'
------------------------------------------------------------

scm
\--- org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r
     +--- com.jcraft:jsch:0.1.54
     +--- com.googlecode.javaewah:JavaEWAH:1.1.6
     +--- org.apache.httpcomponents:httpclient:4.3.6
     |    +--- org.apache.httpcomponents:httpcore:4.3.3
     |    +--- commons-logging:commons-logging:1.1.3
     |    \--- commons-codec:commons-codec:1.6
     \--- org.slf4j:slf4j-api:1.7.2

A web-based, searchable dependency report is available by adding the --scan option.

找出已選取的相依性版本

一個專案可能直接或間接要求同一個相依性的兩個不同版本。Gradle 會套用 版本衝突解決 來確保相依性圖表中只存在一個相依性版本。下列範例會引發與 commons-codec:commons-codec 的衝突，而 commons-codec:commons-codec 是以直接相依性和 JGit 的傳遞相依性新增的

build.gradle.kts
repositories {
    mavenCentral()
}

configurations {
    create("scm")
}

dependencies {
    "scm"("org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r")
    "scm"("commons-codec:commons-codec:1.7")
}
build.gradle
repositories {
    mavenCentral()
}

configurations {
    scm
}

dependencies {
    scm 'org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r'
    scm 'commons-codec:commons-codec:1.7'
}

在 建置掃描 中的相依性樹狀圖會顯示衝突資訊。按一下相依性並選取「所需」標籤，即可查看相依性的選擇原因和來源。

dependency management dependency insight report build scan

相依性見解

Gradle 提供內建的 dependencyInsight 任務，用於從命令列呈現相依性見解報告。相依性見解提供單一 組態 中單一相依性的資訊。給定相依性，您可以找出選擇原因和來源。

dependencyInsight 接受下列參數

--dependency <dependency>（強制）

要調查的相依性。您可以提供完整的 group:name 或其一部分。如果有多個相依性符合，Gradle 會產生涵蓋所有符合相依性的報告。

--configuration <name>（強制）

解析給定相依性的相依性組態。對於使用 Java 外掛程式 的專案來說，這個參數是選用的，因為外掛程式提供預設值 compileClasspath。

--single-path（選用）

只呈現到相依性的單一路徑。

下列程式碼片段示範如何執行「scm」組態中名為「commons-codec」的相依性的所有路徑的相依性見解報告

> gradle -q dependencyInsight --dependency commons-codec --configuration scm
commons-codec:commons-codec:1.7
  Variant default:
    | Attribute Name    | Provided | Requested |
    |-------------------|----------|-----------|
    | org.gradle.status | release  |           |
   Selection reasons:
      - By conflict resolution: between versions 1.7 and 1.6

commons-codec:commons-codec:1.7
\--- scm

commons-codec:commons-codec:1.6 -> 1.7
\--- org.apache.httpcomponents:httpclient:4.3.6
     \--- org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r
          \--- scm

A web-based, searchable dependency report is available by adding the --scan option.

如需組態的更多資訊，請參閱 相依性組態文件。

選擇原因

相依性見解報告的「選擇原因」區段會列出選擇相依性的原因。請參閱下表，了解所使用的不同術語的意義

表 1. 術語
原因 意義

(不存在)

除了直接或傳遞的參考之外，沒有其他原因。

已要求：<text>

相依性出現在圖形中，且包含 because 文字。

已要求：與版本 <versions> 不符

相依性出現 動態版本，其中不包含列出的版本。後面可能會接續 because 文字。

已要求：拒絕版本 <versions>

相依性出現 豐富版本，其中包含一個或多個 reject。後面可能會接續 because 文字。

根據衝突解決：在版本 <version> 之間

此依賴項出現多次，並有不同的版本要求。這會導致衝突解決，以選擇最合適的版本。

依限制

一個依賴項限制參與了版本選擇。後面可能會接續一個because文字。

依祖先

有一個豐富版本，其中包含一個strictly，用來強制執行此依賴項的版本。

依規則選取

一個依賴項解析規則推翻了預設的選擇程序。後面可能會接續一個because文字。

拒絕：依規則拒絕，原因為

一個ComponentSelection.reject拒絕了給定的版本的依賴項。

拒絕：版本：<屬性資訊>

此依賴項有一個動態版本，且有些版本與請求的屬性不符。

強制

此建置會透過強制平台或解析策略來強制執行依賴項的版本。

如果有多個選擇原因，則見解報告會列出所有原因。

疑難排解

版本衝突

如果選取的版本與您的預期不符，Gradle 提供了一系列工具來協助您控制傳遞依賴項。

變異選擇錯誤

有時會在變異選擇層級發生選擇錯誤。請參閱專門章節，以了解這些錯誤以及如何解決它們。

不安全的組態解析錯誤

解析組態可能會對 Gradle 的專案模型造成副作用。因此，Gradle 必須管理對每個專案組態的存取。有許多方法可能會不安全地解析組態。例如

  • 一個專案中的工作會在工作動作中直接解析另一個專案中的組態。

  • 任務會將其他專案的設定指定為輸入檔案集合。

  • 一個專案的建置指令碼會在評估期間解析另一個專案的設定。

  • 專案設定會在設定檔中解析。

Gradle 會針對每個不安全的存取產生棄用警告。不安全的存取可能會造成不確定的錯誤。您應該修正建置中的不安全存取警告。

在大部分情況下，您可以透過建立對其他專案的跨專案相依性來解決不安全的存取。請參閱在專案間分享輸出的說明文件以取得更多資訊。

如果您發現無法使用這些技術解決的用例，請透過提交GitHub Issue讓我們知道。