Maven 打包排除特定依赖的完整指南（详细方法 + 示例）
前言
在使用 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 依赖中声明要排除的子依赖。