调试依赖项解析错误
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
添加依赖项时，您可能会遇到所需的依赖项问题
并且不同依赖项版本之间存在冲突。
下面介绍了如何分析依赖关系图并解决出现的常见问题。
有关修复涉及自定义 build 的依赖项解析错误的指南
逻辑，请参阅
自定义依赖项解析策略。
查看模块依赖项
一些直接依赖项可能具有自己的依赖项。此类依赖项称为“传递依赖项”。Gradle 将会自动为您收集并添加这些传递依赖项，无需您手动逐一加以声明。
Android Plugin for Gradle 提供了一项任务，用来列出 Gradle 为给定模块解析的依赖项。
对于每个模块，报告还会根据 build 变体、测试源代码集和类路径对依赖项进行分组。下面是一个应用模块的依赖项示例报告，其中按该模块的调试 build 变体的运行时类路径和该模块的插桩测试源代码集的编译类路径对依赖项进行了分组。
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 解析配置时，测试配置始终包含 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 的界面搜索包含重复类的依赖项，具体操作步骤如下：
- 从菜单栏中依次选择 Navigate > Class。
- 在弹出式搜索对话框中，确保已勾选 Include non-project items 旁边的框。
- 输入 build 错误中出现的类的名称。
- 检查结果以查找包含该类的依赖项。
下面几部分介绍您可能会遇到的不同类型的依赖项解析错误及其修复方法。
修复重复类错误
如果某个类多次出现在运行时类路径上，您会收到一条与以下内容类似的错误：
Program type already present com.example.MyClass
此错误通常是下列其中一种情况所致：
- 二进制文件依赖项包含一个库，该库也作为直接依赖项包含在您的应用中。例如，您的应用声明直接依赖于库 A 和库 B，但库 A 已在其二进制文件中包含库 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 和/或其关联公司的注册商标。
最后更新时间 (UTC)：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"]],["最后更新时间 (UTC)：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."]]
