maven:maven-shade-plugin插件被误解的参数 keepDependenciesWithProvidedScope

一、问题的诞生：官方文档的模糊描述

在 maven-shade-plugin 的官方文档中，关于keepDependenciesWithProvidedScope 参数的描述仅有简单一句¹：

keepDependenciesWithProvidedScope

When true, dependencies are kept in the pom but with scope ‘provided’; when false, the dependency is removed.

这导致许多开发者（包括我）产生误解，认为该参数可以强制将 provided 作用域的依赖打包到最终 JAR 中。实际上，这是一个错误认知。

---

二、源码揭秘：参数的真实作用

通过分析 org.apache.maven.plugins.shade.mojo.ShadeMojo 源码²，我们发现：

1. 生效条件

if (createDependencyReducedPom) {
    // 当且仅当 createDependencyReducedPom=true 时
    createDependencyReducedPom(artifactIds);
}

keepDependenciesWithProvidedScope 仅在 createDependencyReducedPom=true 时生效。

---

2. 实际行为

在生成 dependency-reduced-pom.xml 文件时，插件会执行以下逻辑：

private void createDependencyReducedPom(Set<String> artifactsToRemove){
    // 源码片段简化
    if (!keepDependenciesWithProvidedScope) {
        // 移除所有 provided 作用域的依赖
        dependencies.removeIf(d -> "provided".equals(d.getScope()));
    }
}

这意味着：

• 当 keepDependenciesWithProvidedScope=true：保留 provided 依赖在精简 POM 中
• 当 keepDependenciesWithProvidedScope=false（默认）：从精简 POM 中移除 provided 依赖

---

三、配置示例：眼见为实

场景描述

假设项目依赖如下：

<dependency>
    <groupId>org.example</groupId>
    <artifactId>lib-d</artifactId>
    <version>1.0</version>
    <scope>provided</scope>
</dependency>

---

配置对比

配置项	值	生成的 dependency-reduced-pom.xml
createDependencyReducedPom=true keepDependenciesWithProvidedScope=false	默认	移除 lib-d 依赖
createDependencyReducedPom=true keepDependenciesWithProvidedScope=true	特殊需求	保留 lib-d 依赖

---

四、常见误解澄清

误解 1：控制 JAR 打包内容

真相：该参数 不控制依赖是否被打包到 JAR，仅影响 dependency-reduced-pom.xml 的内容。 provided 依赖不会被shade插件打包到JAR。

误解 2：与 minimizeJar 相关

真相：与 minimizeJar 参数无关。两者分别控制：

• minimizeJar：优化 JAR 文件大小
• keepDependenciesWithProvidedScope：控制精简 POM 的依赖范围

---

五、正确使用姿势

适用场景

当你的项目需要：

1. 生成 dependency-reduced-pom.xml
2. 保留 provided 依赖在精简 POM 中（例如：下游项目需要知道这些依赖的存在）

配置模板

<configuration>
    <createDependencyReducedPom>true</createDependencyReducedPom>
    <keepDependenciesWithProvidedScope>true</keepDependenciesWithProvidedScope>
    <!-- 其他配置 -->
</configuration>

---

六、总结

keepDependenciesWithProvidedScope 是一个典型的 “文档描述 < 源码真相” 案例。其核心要点：

1. 仅当 createDependencyReducedPom=true 时生效
2. 仅影响生成的 POM 文件，不控制 JAR 打包
3. 用于保留 provided 依赖在精简 POM 中的元数据

下次遇到这个参数时，请记住：它只是 POM 文件的管家，不是 JAR 打包的搬运工。

---

参考资料

---

1. 《keepDependenciesWithProvidedScope》 ↩︎

2. ShadeMojo.java ↩︎