前言
在使用 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 依赖中声明要排除的子依赖。