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

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

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

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 源码^2^，我们发现：

1. 生效条件

java 复制代码

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

keepDependenciesWithProvidedScope 仅在 createDependencyReducedPom=true 时生效。

2. 实际行为

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

java 复制代码

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

这意味着：

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

三、配置示例：眼见为实

场景描述

假设项目依赖如下：

xml 复制代码

<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 的依赖范围

五、正确使用姿势

适用场景

当你的项目需要：

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

配置模板