偵錯依附元件解決方案錯誤
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
新增依附元件時，可能會遇到必要的依附元件問題
產生的內容，且不同依附元件版本之間的衝突。
以下說明如何分析依附元件圖表，並修正可能發生的常見問題。
如需修正與自訂建構相關的依附元件解析錯誤相關指引
邏輯，請參閱
自訂依附元件解析策略。
檢視模組依附元件
部分直接依附元件可能有自己的依附元件。這就是所謂的遞移依附元件。Gradle 會自動為您收集並新增這類依附元件，讓您不必手動宣告各項遞移依附元件。Gradle 適用的 Android 外掛程式提供的工作會顯示 Gradle 解析特定模組的依附元件清單。
各個模組也會依據建構變數、測試來源集和類別路徑將依附元件分組。以下是應用程式模組偵錯類別變數的執行階段類別路徑，以及編譯檢測設備測試來源集的類別路徑的範例報表。
debugRuntimeClasspath - Dependencies for runtime/packaging
+--- :mylibrary (variant: debug)
+--- com.google.android.material:material:1.0.0@aar
+--- androidx.appcompat:appcompat:1.0.2@aar
+--- androidx.constraintlayout:constraintlayout:1.1.3@aar
+--- androidx.fragment:fragment:1.0.0@aar
+--- androidx.vectordrawable:vectordrawable-animated:1.0.0@aar
+--- androidx.recyclerview:recyclerview:1.0.0@aar
+--- androidx.legacy:legacy-support-core-ui:1.0.0@aar
...
debugAndroidTest
debugAndroidTestCompileClasspath - Dependencies for compilation
+--- androidx.test.ext:junit:1.1.0@aar
+--- androidx.test.espresso:espresso-core:3.1.1@aar
+--- androidx.test:runner:1.1.1@aar
+--- junit:junit:4.12@jar
...
如要執行工作，請依照下列步驟操作：
- 依序選取「View」>「Tool Windows」>「Gradle」，或者點選工具視窗列中的「Gradle」圖示
。
- 展開「AppName」>「Tasks」>「Android」，然後按兩下「androidDependencies」。Gradle 執行工作之後，「Run」視窗應該會開啟以顯示輸出內容。
如要進一步瞭解如何在 Gradle 中管理依附元件，請參閱
依附元件管理基本概念
。
排除遞移依附元件
隨著應用程式的範圍擴大，可包含多種依附元件，包括直接依附元件和遞移依附元件 (應用程式匯入的程式庫所依附的程式庫)。如要不再需要排除遞移依附元件，您可以使用 exclude 關鍵字，如下所示：
Kotlin
dependencies {
implementation("some-library") {
exclude(group = "com.example.imgtools", module = "native")
}
}
Groovy
dependencies {
implementation('some-library') {
exclude group: 'com.example.imgtools', module: 'native'
}
}
從測試設定中排除遞移依附元件
假使您需要從測試中排除某些遞移依附元件，上述的程式碼範例可能無法正常運作。這是因為測試設定 (例如 androidTestImplementation) 會擴充模組的 implementation 設定。也就是說，Gradle 會在 Gradle 解析設定時一律包含 implementation 依附元件。
因此，如要從測試中排除遞移依附元件，您必須在執行時間執行，如下所示：
Kotlin
android.testVariants.all {
compileConfiguration.exclude(group = "com.jakewharton.threetenabp", module = "threetenabp")
runtimeConfiguration.exclude(group = "com.jakewharton.threetenabp", module = "threetenabp")
}
Groovy
android.testVariants.all { variant ->
variant.getCompileConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
variant.getRuntimeConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
}
注意：您仍然可以在依附元件區塊中使用 exclude 關鍵字，如「排除遞移依附元件」部分中的原始代碼範例所示，以省略特定於測試設定且不包含在其他設定中的遞移依附元件。
修正依附元件解決方案錯誤
在應用程式專案中加入多個依附元件時，這些直接和遞移的依附元件可能會彼此衝突。Android Gradle 外掛程式會試著圓滿地解決這些衝突，但有些衝突可能會導致編譯時間或執行階段錯誤。
為協助您調查哪些依附元件導致錯誤，請查看應用程式的依附元件樹狀結構，找出重複出現或衝突版本的依附元件。
假使您無法辨別重複的依附元件，請嘗試使用 Android Studio 的 UI 搜尋包含重複類別的依附元件，如下所示：
- 在選單列中依序選取「Navigate」>「Class」。
- 在彈出式搜尋對話方塊中，確定已勾選「Include non-project items」旁的方塊。
- 輸入建構錯誤中顯示的類別名稱。
- 檢查含有類別的依附元件結果。
以下各節說明您可能會遇到的各種依附元件的解決錯誤及修正方式。
修正重複的類別錯誤
假使類別在執行階段類別路徑上多次出現，您會看到如下的錯誤：
Program type already present com.example.MyClass
此錯誤的常見原因如下：
- 二進位檔依附元件包括一個程式庫，您的應用程式也將其作為直接依附元件包含在內。舉例來說，您的應用程式宣告了程式庫 A 和程式庫 B 的直接依附元件，但程式庫 A 的二進位檔中已包含程式庫 B。
- 如要解決此問題，請移除程式庫 B 作為直接依附元件。
- 您的應用程式在同一個程式庫中，儲存本機二進位檔依附元件和遠端二進位檔依附元件。
修正類別路徑之間的衝突
Gradle 解析編譯類別路徑時，會先解析執行階段類別路徑，並使用結果來決定要將哪些依附元件版本新增至編譯類別路徑。換句話說，執行階段類別路徑會判斷下游類別路徑中相同依附元件的必要版本號碼。
您應用程式的執行階段類別路徑也會決定 Gradle 需要的應版本號碼，才能比對應用程式的測試 APK 的執行階段類別路徑。圖 1 說明類別路徑的階層結構。
圖 1. 出現在多個類別路徑中的依附元件版本編號必須符合此階層。
當相同依附元件的不同版本出現在多個類路徑中，便可能會發生衝突。舉例來說，當您的應用程式包含使用 implementation 依附元件設定的依附元件版本，而程式庫模組包含使用 runtimeOnly 設定的另一個依附元件版本時，便可能會發生衝突。
解決執行階段中編譯依附元件和編譯時間類別路徑時，Android Gradle 外掛程式 3.3.0 以上版本會嘗試自動修正特定的下游版本衝突。舉例來說，當執行階段類別路徑內含程式庫 A 版本 2.0，而編譯類別路徑內含程式庫 A 版本 1.0，此時外掛程式會自動將編譯類別路徑內的依附元件更新為程式庫 A 版本 2.0，以便防止發生錯誤。
然而，假使執行階段類別路徑包含程式庫 A 版本 1.0，且編譯類別路徑包含程式庫 A 版本 2.0，則外掛程式不會將編譯類別路徑的依附元件降級至程式庫 A 版本 1.0，但您仍然會取得錯誤，如下所示：
Conflict with dependency 'com.example.library:some-lib:2.0' in project 'my-library'.
Resolved versions for runtime classpath (1.0) and compile classpath (2.0) differ.
如要解決這個問題，請按照下列其中一種做法進行：
- 將所需依附元件版本新增為程式庫模組的
api 依附元件。也就是說，只有您的程式庫模組會宣告依附元件，但應用程式模組也可以遞移地存取其 API。
- 或者，您可以在這兩種模組中宣告依附元件，但請務必確保每個模組都使用相同版本的依附元件。建議設定全專案的屬性，確保整個專案中各項依附元件的版本保持一致。
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間：2025-07-27 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-07-27 (世界標準時間)。"],[],[],null,["# Debug dependency resolution errors\n\nWhen you add a dependency, you might encounter issues with dependencies required\nby the original dependency, and conflicts among different dependency versions.\nHere's how to analyze your dependency graph and fix common issues that arise.\n\nFor guidance on fixing dependency resolution errors that involve custom build\nlogic, see\n[Custom dependency resolution strategies](/build/custom-build-logic#custom_dep_resolutions).\n\nView module dependencies\n------------------------\n\nSome direct dependencies may have dependencies of their own. These are called\n*transitive dependencies*. Rather than requiring you to manually declare each\ntransitive dependency, Gradle automatically gathers and adds them for you.\nThe Android plugin for Gradle provides a task that displays a list of the\ndependencies Gradle resolves for a given module.\n\nFor each module, the report\nalso groups the dependencies based on build variant, testing source set, and\nclasspath. The following is sample report for an app module's runtime\nclasspath of its debug build variant and compile classpath of its instrumented\ntest source set. \n\n debugRuntimeClasspath - Dependencies for runtime/packaging\n +--- :mylibrary (variant: debug)\n +--- com.google.android.material:material:1.0.0@aar\n +--- androidx.appcompat:appcompat:1.0.2@aar\n +--- androidx.constraintlayout:constraintlayout:1.1.3@aar\n +--- androidx.fragment:fragment:1.0.0@aar\n +--- androidx.vectordrawable:vectordrawable-animated:1.0.0@aar\n +--- androidx.recyclerview:recyclerview:1.0.0@aar\n +--- androidx.legacy:legacy-support-core-ui:1.0.0@aar\n ...\n\n debugAndroidTest\n debugAndroidTestCompileClasspath - Dependencies for compilation\n +--- androidx.test.ext:junit:1.1.0@aar\n +--- androidx.test.espresso:espresso-core:3.1.1@aar\n +--- androidx.test:runner:1.1.1@aar\n +--- junit:junit:4.12@jar\n ...\n\nTo run the task, proceed as follows:\n\n1. Select **View \\\u003e Tool Windows \\\u003e Gradle** (or click **Gradle** in the tool windows bar).\n2. Expand **\u003cvar translate=\"no\"\u003eAppName\u003c/var\u003e \\\u003e Tasks \\\u003e android** and double-click **androidDependencies** . After Gradle executes the task, the **Run** window should open to display the output.\n\nFor more information about managing dependencies in Gradle, see\n[Dependency management basics](http://www.gradle.org/docs/current/userguide/artifact_dependencies_tutorial.html)\nin the Gradle User Guide.\n\nExclude transitive dependencies\n-------------------------------\n\nAs an app grows in scope, it can contain a number of dependencies including\ndirect dependencies and transitive dependencies (libraries which your app's\nimported libraries depend on).\nTo exclude transitive dependencies that you no longer need, you can use the\n`exclude` keyword as given below: \n\n### Kotlin\n\n```kotlin\ndependencies {\n implementation(\"some-library\") {\n exclude(group = \"com.example.imgtools\", module = \"native\")\n }\n}\n```\n\n### Groovy\n\n```groovy\ndependencies {\n implementation('some-library') {\n exclude group: 'com.example.imgtools', module: 'native'\n }\n}\n```\n\n### Exclude transitive dependencies from test configurations\n\nIf you need to exclude certain transitive dependencies from your tests,\nthe code sample shown above might not work as expected. That's because a test\nconfiguration (e.g., `androidTestImplementation`) extends the module's\n`implementation` configuration. That is, it always contains `implementation`\ndependencies when Gradle resolves the configuration.\n\nSo, to exclude transitive dependencies from your tests, you must do so at\nexecution time as shown below: \n\n### Kotlin\n\n```kotlin\nandroid.testVariants.all {\n compileConfiguration.exclude(group = \"com.jakewharton.threetenabp\", module = \"threetenabp\")\n runtimeConfiguration.exclude(group = \"com.jakewharton.threetenabp\", module = \"threetenabp\")\n}\n```\n\n### Groovy\n\n```groovy\nandroid.testVariants.all { variant -\u003e\n variant.getCompileConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'\n variant.getRuntimeConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'\n}\n```\n\n**Note:** You can still use the `exclude` keyword\nin the dependencies block as shown in the original code sample from the\n[**Exclude transitive dependencies**](#exclude_dependencies)\nsection to omit transitive dependencies that are specific to the test\nconfiguration and are not included in other configurations.\n\nFix dependency resolution errors\n--------------------------------\n\nWhen you add multiple dependencies to your app project, those direct and\ntransitive dependencies might conflict with one another. The Android Gradle\nplugin tries to resolve these conflicts gracefully, but some conflicts may lead\nto compile time or runtime errors.\n\nTo help you investigate which dependencies are contributing to errors,\n[inspect your app's dependency tree](#view-dependency-tree) and look for\ndependencies that appear more than once or with conflicting versions.\n\nIf you can't easily identify the duplicate dependency, try using Android\nStudio's UI to search for dependencies that include the duplicate class\nas follows:\n\n1. Select **Navigate \\\u003e Class** from the menu bar.\n2. In the pop-up search dialog, make sure that the box next to **Include non-project items** is checked.\n3. Type the name of the class that appears in the build error.\n4. Inspect the results for the dependencies that include the class.\n\nThe following sections describe the different types of dependency resolution\nerrors you may encounter and how to fix them.\n\n### Fix duplicate class errors\n\nIf a class appears more than once on the runtime classpath, you get an\nerror similar to the following: \n\n```\nProgram type already present com.example.MyClass\n```\n\nThis error typically occurs due to one of the following circumstances:\n\n- A binary dependency includes a library that your app also includes as a direct dependency. For example, your app declares a direct dependency on Library A and Library B, but Library A already includes Library B in its binary.\n - **To resolve this issue**, remove Library B as a direct dependency.\n- Your app has a local binary dependency and a remote binary dependency on the same library.\n - **To resolve this issue**, remove one of the binary dependencies.\n\n### Fix conflicts between classpaths\n\nWhen Gradle resolves the compile classpath, it first resolves the *runtime*\nclasspath and uses the result to determine what versions of dependencies should\nbe added to the compile classpath. In other words, the runtime\nclasspath determines the required version numbers for identical dependencies on\ndownstream classpaths.\n\nYour app's runtime classpath also determines the version numbers that Gradle\nrequires for matching dependencies in the runtime classpath for the app's test\nAPK. The hierarchy of classpaths is described in figure 1.\n\n\n**Figure 1.** Version numbers of dependencies\nthat appear across multiple classpaths must match according to this\nhierarchy.\n\n\u003cbr /\u003e\n\nA conflict where different versions of the same dependency appears across\nmultiple classpaths might occur when, for example, your app includes a version of\na dependency using the `implementation`\n[dependency configuration](/build/dependencies#dependency_configurations)\nand a library module includes a different version of the dependency using the\n`runtimeOnly` configuration.\n\nWhen resolving dependencies on your runtime and compile time classpaths, Android\nGradle plugin 3.3.0 and higher attempt to automatically fix certain downstream\nversion conflicts. For example, if the runtime classpath includes Library A\nversion 2.0 and the compile classpath includes Library A version 1.0, the plugin\nautomatically updates the dependency on the compile classpath to Library A\nversion 2.0 to avoid errors.\n\nHowever, if the runtime classpath includes Library A version 1.0 and the compile\nclasspath includes Library A version 2.0, the plugin does not downgrade the\ndependency on the compile classpath to Library A version 1.0, and you still get\nan error similar to the following: \n\n```\nConflict with dependency 'com.example.library:some-lib:2.0' in project 'my-library'.\nResolved versions for runtime classpath (1.0) and compile classpath (2.0) differ.\n```\n\nTo resolve this issue, do one of the following:\n\n- Include the desired version of the dependency as an `api` dependency to your library module. That is, only your library module declares the dependency, but the app module will also have access to its API, transitively.\n- Alternatively, you can declare the dependency in both modules, but you should make sure that each module uses the same version of the dependency. Consider [configuring project-wide properties](/studio/build/gradle-tips#configure-project-wide-properties) to ensure versions of each dependency remain consistent throughout your project."]]
