排除传递依赖：per-dependency 排除、全局排除、排除与禁止依赖对比

原理：为什么需要排除传递依赖

Gradle 默认自动解析并拉取所有传递依赖，但当引入的库携带了不需要、版本冲突或安全漏洞的间接依赖时，构建产物会膨胀甚至编译失败。排除（exclude）的本质是在依赖图上“剪枝”——移除特定 group:module，让 Gradle 像是从未解析过该坐标。禁止依赖则是在声明时直接关闭传递性（transitive = false）或强制指定版本（force），不依赖裁剪，而是从源头上阻止整个传递链。

实现流程

1. 分析依赖树：执行 gradle dependencies --configuration runtimeClasspath 查看传递依赖列表，标记需要排除的坐标。
2. 选择排除方式：若该冲突只出现在单个依赖上，使用 per-dependency exclude；若多个依赖都引入同一个不需要的模块，使用全局配置 exclude。
3. 编写排除规则：在 dependencies 块或 configurations.all 中声明 exclude group:..., module:...。
4. 验证结果：重新执行 dependencies 任务，确认被排除的模块不再出现在树中。
5. 运行编译/测试：确保排除后不会出现 ClassNotFoundException 等缺失错误。

配置与代码示例

per-dependency 排除

在单个依赖声明内部使用 exclude，只影响该依赖的传递链：

dependencies {
    implementation('com.example:library-a:1.0') {
        exclude group: 'org.unwanted', module: 'ugly-lib'
        // 可以写多个 exclude
        exclude group: 'com.old', module: 'deprecated-log'
    }
}

全局排除

在 configurations.all 或特定配置中声明，影响当前项目内所有依赖及其传递依赖：

configurations.all {
    // 排除 org.unwanted:ugly-lib 所有版本
    exclude group: 'org.unwanted', module: 'ugly-lib'
    // 只排除 group，不指定 module
    exclude group: 'com.old.log'
}

禁止依赖（transitive false 与 force）

关闭某个依赖的整个传递链：

dependencies {
    implementation('com.example:library-a:1.0') {
        transitive = false   // 该依赖的所有传递依赖都不再引入
    }
    // 使用 force 强制指定版本（优先于传递依赖中的版本）
    implementation('org.unwanted:ugly-lib:1.2') {
        force = true
    }
}

调试与验证

执行以下命令查看依赖树排除效果：

gradle dependencies --configuration compileClasspath

输出中若出现 (*) 或 (c) 等标记表示依赖被冲突解决或约束覆盖；被 exclude 的模块会直接从树中消失，不会出现任何版本行。若排除后编译报错，可临时注释 exclude 再运行 dependencies 确认依赖是否确实被正常引入。

部署影响

排除只影响当前项目的解析结果，不会修改库本身的 pom.xml 或 ivy.xml。发布到仓库的构件（jar/war）中不会包含被排除的模块，但仍需注意：排除的模块若在运行时通过其他路径（如父项目、类加载器）出现，仍可能引发冲突。全局排除对所有配置生效（除非用 configurations.named('implementation') 限定），发布到其他项目时，排除规则不会传播——消费者的构建需独立声明。

常见错误

• 排除坐标错误：写错 group 或 module，导致排除无效。建议直接复制自 dependencies 输出中的坐标。
• 过度排除：全局排除时不小心把项目自身依赖的核心库排除，引发编译失败。使用 exclude group: '...' 时尽量指定 module，避免误伤。
• 排除后仍存在：若同一坐标被其他未排除的依赖引入，仍需单独排除；或者该坐标是根依赖的直接依赖（非传递），exclude 无效。
• 与 transitive=false 冲突：同时设置 transitive = false 和 exclude 会冗余，且 transitive = false 更暴力，建议只选其一。

性能与稳定性优化

• 粒度优先：优先使用 per-dependency exclude，避免全局排除影响未知依赖。
• 结合 constraints：对于版本冲突而非移除，使用 constraints 或 force 更稳定，排除会移除模块，可能导致 NoClassDefFoundError。
• 定期审计：每季度运行一次 dependencies 检查是否存在旧排除规则，及时清理。
• 使用 Gradle 提供的 dependencyInsight：gradle dependencyInsight --dependency ugly-lib --configuration runtimeClasspath 快速定位引入来源。

排除与禁止依赖对比