Maven-Exclude-Dependencies
前言
在使用 Maven 构建 Java 项目时，我们常常需要对项目的打包过程进行精细化控制，尤其是希望排除某些特定的依赖库。这可能是为了减小最终构建产物的体积、避免版本冲突，或者仅仅是为了满足不同环境下的部署需求。
本文将详细介绍如何在 Maven 打包过程中排除特定依赖，涵盖多种常见插件和配置方式，帮助你灵活控制项目的打包内容。
一、理解 Maven 的依赖作用域（Scope）
在深入讨论排除依赖之前，先了解 Maven 中的依赖作用域是非常重要的。不同的作用域决定了依赖是否会被包含在构建输出中：
| Scope | 描述 |
|---|---|
| compile | 默认作用域，适用于所有阶段（编译、测试、运行） |
| provided | 编译和测试阶段可用，但不会被打包进最终输出（如 Servlet API） |
| runtime | 运行和测试阶段需要，但编译不需要（如 JDBC 驱动 |
| test | 仅用于测试阶段，不会被打包 |
| system | 类似于 provided，但必须显式指定本地路径 |
| import | 仅用于 <dependencyManagement> 中导入其他 POM 的依赖 |
最佳实践建议：优先使用合适的 scope 来控制依赖是否被打包，而不是通过插件强行剔除。
二、使用 Maven Shade Plugin 排除依赖
如果你使用的是 maven-shade-plugin 来构建一个包含所有依赖的 fat jar（即 uber jar），可以通过 <excludes> 标签来排除特定依赖。
示例配置：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<excludes>
<exclude>com.example:unwanted-library</exclude>
<exclude>org.slf4j:slf4j-simple</exclude>
</excludes>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.example.Main</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
说明：
<exclude>的格式为groupId:artifactId，可以精确到版本号。- 适合用于构建包含多个模块和依赖的单体 JAR 包。
三、使用 Maven Assembly Plugin 排除依赖
如果你使用 maven-assembly-plugin 来打包一个包含依赖的 zip/jar 包，也可以通过 <excludes> 来排除某些依赖。
示例配置：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
<archive>
<manifest>
<mainClass>com.example.Main</mainClass>
</manifest>
</archive>
<excludes>
<exclude>com.example:unwanted-library</exclude>
<exclude>org.slf4j:slf4j-api</exclude>
</excludes>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
提示：Assembly 插件还支持自定义 assembly.xml 文件，实现更细粒度的控制。
四、使用 Maven Jar Plugin 排除资源或类文件
默认的 maven-jar-plugin 不会把依赖打进 JAR 包中，但如果你有特殊需求（如手动管理 lib 目录），可以用来排除某些资源或类文件。
示例配置（排除资源）：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<excludes>
<exclude>**/unwanted/**</exclude>
</excludes>
</configuration>
</plugin>
五、使用 Maven Dependency Plugin 清理依赖
如果你想在打包前主动清理某些依赖，可以使用 maven-dependency-plugin 来复制依赖并排除部分库。
示例配置：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.6.0</version>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/lib</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
<excludes>
<exclude>com.example:unwanted-library</exclude>
</excludes>
</configuration>
</execution>
</executions>
</plugin>
此方法适合手动构建 lib 目录，并配合 shell 脚本或 Dockerfile 使用。
六、Docker 构建中排除依赖（Maven + Docker）
如果你使用 Maven 构建镜像（如结合 Jib、Dockerfile 等），可以在构建应用 JAR 包时就排除依赖，再将其 COPY 到 Docker 镜像中。
示例（结合 jib-maven-plugin）：
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>jib-maven-plugin</artifactId>
<version>3.3.2</version>
<configuration>
<container>
<entrypoint>
<arg>java</arg>
<arg>-cp</arg>
<arg>/app/resources:/app/classes:/app/libs/*</arg>
<arg>com.example.Main</arg>
</entrypoint>
</container>
<extraDirectories>
<paths>
<path>
<from>src/main/resources</from>
<into>/app/resources</into>
</path>
</paths>
</extraDirectories>
</configuration>
</plugin>
在此示例中，你可以先通过其他方式控制哪些依赖被放入 /app/libs/。
七、使用 <scope> 显式排除依赖
最简单且推荐的方式是直接在 pom.xml 中设置依赖的作用域为 test 或 provided，这样它们就不会被打包进最终输出。
示例：
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>4.0.1</version>
<scope>provided</scope>
</dependency>
Maven 会根据作用域自动决定是否将该依赖包含在构建输出中。
八、使用 <optional> 标记依赖为可选
如果你开发的是一个库（library），并且某个依赖不是必需的，可以将其标记为 <optional>true</optional>，这样引入你的库的项目可以选择是否包含这个依赖。
示例：
<dependency>
<groupId>com.example</groupId>
<artifactId>some-utils</artifactId>
<version>1.0.0</version>
<optional>true</optional>
</dependency>
注意：<optional> 不会影响当前项目的打包行为，而是影响下游项目的依赖管理。
九、使用 <exclusion> 排除传递性依赖
有时你想排除某个依赖的子依赖（transitive dependency），可以使用 <exclusions>。
示例：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
<exclusion>
<groupId>org.slf4j</groupId>
<artifactId>log4j-over-slf4j</artifactId>
</exclusion>
</exclusions>
</dependency>
这种方式非常适合解决依赖冲突或精简依赖树。
十、综合建议与最佳实践
| 场景 | 推荐做法 |
|---|---|
| 测试依赖不打包 | 设置 <scope>test</scope> |
| 容器已提供依赖（如 Tomcat、JDK） | 设置 <scope>provided</scope> |
| 某些依赖不想被打入最终 JAR/WAR | 使用 Shade / Assembly 插件配置 <excludes> |
| 排除某个依赖的子依赖 | 使用 <exclusions> 标签 |
| 控制依赖是否传递给下游项目 | 使用 <optional>true</optional> |
| 构建 lib 目录时排除某些库 | 使用 maven-dependency-plugin 的 <excludes> |
| 构建 Docker 镜像时排除依赖 | 结合上述方法先处理好 JAR 再 COPY |
总结
Maven 提供了多种灵活的方式来排除特定依赖，从简单的 <scope>
到复杂的插件配置，开发者可以根据实际需求选择最合适的方法。合理使用这些技巧不仅可以减小最终包的体积，还能有效避免依赖冲突问题，提高构建效率和部署稳定性。
常见问答
-
Q：我只想排除某个依赖的一个 jar 文件？
-
A：可以使用
<exclusion>排除其子依赖，或者使用插件配置<excludes>。 -
Q：为什么设置了
<scope>provided</scope>依赖仍然被打包？ -
A：检查是否被其他插件强制引入，例如
maven-shade-plugin。 -
Q：我想在 Spring Boot 项目中排除某些 starter 自带的依赖怎么办？
-
A：使用
<exclusions>标签，在对应的 starter 依赖中声明要排除的子依赖。