Gradle 提供工具來導航相依性管理的結果，讓您可以更精確地了解 Gradle 如何以及為何解析相依性。您可以呈現完整的相依性圖形、識別給定相依性的來源，並查看為何選擇特定版本。相依性可能來自建置腳本宣告或遞移關係。

若要視覺化相依性，您可以使用

使用 dependencies 任務列出專案相依性

Gradle 提供內建的 dependencies 任務，以從命令列呈現相依性樹狀結構。依預設，此任務會顯示 配置 內所有 單一專案 的相依性。相依性樹狀結構會顯示每個相依性的選定版本，並提供衝突解決的相關資訊。

dependencies 任務對於分析遞移相依性特別有用。雖然您的建置檔會列出直接相依性，但此任務可協助您了解在建置期間解析了哪些遞移相依性。

$ ./gradlew dependencies
若要呈現 在 buildscript classpath 配置中宣告 的相依性圖形，請使用 buildEnvironment 任務。

了解輸出註解

$ ./gradlew :app:dependencies

> Task :app:dependencies

------------------------------------------------------------
Project ':app'
------------------------------------------------------------

annotationProcessor - Annotation processors and their dependencies for source set 'main'.
No dependencies

compileClasspath - Compile classpath for source set 'main'.
\--- com.fasterxml.jackson.core:jackson-databind:2.17.2
     +--- com.fasterxml.jackson.core:jackson-annotations:2.17.2
     |    \--- com.fasterxml.jackson:jackson-bom:2.17.2
     |         +--- com.fasterxml.jackson.core:jackson-annotations:2.17.2 (c)
     |         +--- com.fasterxml.jackson.core:jackson-core:2.17.2 (c)
     |         \--- com.fasterxml.jackson.core:jackson-databind:2.17.2 (c)
     +--- com.fasterxml.jackson.core:jackson-core:2.17.2
     |    \--- com.fasterxml.jackson:jackson-bom:2.17.2 (*)
     \--- com.fasterxml.jackson:jackson-bom:2.17.2 (*)

...

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
configurations {
    create("scm")
}

dependencies {
    "scm"("org.eclipse.jgit:org.eclipse.jgit:4.9.2.201712150930-r")
}
build.gradle
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.

使用 dependencyInsight 任務識別選定的版本

專案可能會直接或遞移地請求相同相依性的兩個不同版本，這可能會導致版本衝突。

以下範例引入了與 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'
}

Gradle 提供內建的 dependencyInsight 任務，以從命令列呈現相依性洞察報告。

相依性洞察提供有關單一 配置 內單一相依性的資訊。給定相依性，您可以識別其版本選擇的原因和來源。

dependencyInsight 接受以下參數

--dependency <dependency> (強制性)

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

--configuration <name> (強制性)

解析給定相依性的相依性配置。對於使用 Java 外掛 的專案，此參數是選用的，因為外掛程式提供 compileClasspath 的預設值。

--single-path (選用)

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

--all-variants (選用)

呈現有關所有變體的資訊，而不僅僅是選定的變體。

以下程式碼片段示範如何針對 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.

了解選擇原因

相依性洞察報告的「選擇原因」區段列出選擇相依性的原因。

原因 含義

(無)

除了參考 (直接或遞移) 之外，沒有其他原因。

要求為：<text>

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

要求為：不符合版本 <versions>

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

要求為：拒絕版本 <versions>

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

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

相依性出現多次，具有不同的版本要求。這導致衝突解決以選擇最合適的版本。

依約束

相依性約束參與了版本選擇。後面可能會接續 because 文字。

依祖先

存在具有 strictly 的 豐富版本，其強制執行此相依性的版本。

依規則選取

相依性解析規則推翻了預設選擇程序。後面可能會接續 because 文字。

拒絕：<version> 依規則，因為 <text>

ComponentSelection.reject 拒絕了給定版本 的相依性。

拒絕：版本 <version>：<attributes information>

相依性具有動態版本，且某些版本不符合要求的屬性。

強制

建置透過強制平台或解析策略強制執行相依性的版本。

如果存在多個選擇原因，洞察報告會列出所有原因。

使用建置掃描取得整體視圖

建置掃描 中的相依性樹狀結構會顯示有關衝突的資訊。

已為上述 commons-codec 範例建立建置掃描，並提供了包含結果的 URL。

前往 Dependencies 標籤並導航至您想要的相依性。選取 Required By 標籤以查看相依性的選擇原因和來源

dependency management dependency insight report build scan

解決不安全的配置解析錯誤

解析配置可能會對 Gradle 的專案模型產生副作用，因此 Gradle 需要管理對每個專案配置的存取權。配置可能以不安全的方式解析有很多種方法。Gradle 會針對每個不安全的存取產生棄用警告。這些都是不良做法，可能會導致奇怪且不確定的錯誤。

如果您的建置有不安全的存取棄用警告，則需要修正。

例如

  • 一個專案中的任務直接解析另一個專案中任務動作中的配置。

  • 一個任務將另一個專案中的配置指定為輸入檔案集合。

  • 一個專案的建置腳本在評估期間解析另一個專案中的配置。

  • 專案配置在設定檔中解析。

在大多數情況下，可以透過在另一個專案上建立跨專案相依性來解決此問題。請參閱在專案之間共用輸出的文件以取得更多資訊。

如果您發現無法使用這些技術解決的使用案例，請透過提交 GitHub Issue 並遵守我們的問題指南來告知我們。