Maven 插件:maven-jar-plugin 详解

maven-jar-plugin 是 Apache Maven 生态中最基础、最常用的插件之一，负责将项目编译后的 .class 文件和资源打包成标准的 JAR（Java Archive） 文件。它在 Maven 的默认生命周期中自动绑定到 package 阶段，是构建 Java 应用程序不可或缺的一环。

相关链接：

• 官网：https://maven.apache.org/plugins/maven-jar-plugin
• 代码仓库：https://github.com/apache/maven-jar-plugin
• 中央仓库：https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-jar-plugin

一、基本作用

• 将 target/classes 目录下的编译产物（.class 文件、资源文件等）打包为 .jar 文件。
• 支持自定义 JAR 文件的名称、内容、元数据（如 MANIFEST.MF）。
• 可生成主 JAR（包含主代码）和测试 JAR（包含测试代码）。

二、默认绑定与触发时机

在 Maven 的 jar 打包类型（packaging = jar） 项目中，maven-jar-plugin 自动绑定到 package 阶段，无需显式配置即可工作。

<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>my-app</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging><!-- 默认 packaging 为 jar，可以不用配置 -->
</project>

执行 mvn package 时，会自动调用 jar:jar 目标生成 JAR。

三、常用配置项详解

基本配置结构

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.0</version><!-- 推荐使用最新稳定版 -->
<configuration>
<!-- 配置项 -->
</configuration>
</plugin>
</plugins>
</build>

“

✅ 建议始终显式指定版本，避免因 Maven 版本不同导致行为不一致。

自定义 Manifest 文件

通过配置 MANIFEST.MF 内容：

<configuration>
<archive>
<manifest>
<!-- 添加 Class-Path -->
<addClasspath>true</addClasspath>
<classpathPrefix>lib/</classpathPrefix>

<!-- 指定主类（用于可执行 JAR） -->
<mainClass>com.example.Main</mainClass>
</manifest>

<!-- 或直接添加任意 Manifest 条目 -->
<manifestEntries>
<Implementation-Version>${project.version}</Implementation-Version>
<Built-By>MyTeam</Built-By>
<Build-Jdk>${java.version}</Build-Jdk>
</manifestEntries>
</archive>
</configuration>

“

⚠️ 注意：仅靠 maven-jar-plugin 生成的可执行 JAR 不会包含依赖！若需“胖 JAR”，应使用 maven-shade-plugin 或 spring-boot-maven-plugin。

排除或包含特定文件

控制哪些文件被打包进 JAR：

<configuration>
<excludes>
<exclude>**/UnusedClass.class</exclude>
<exclude>config/dev.properties</exclude>
</excludes>
<includes>
<include>**/*.class</include>
<include>config/prod.properties</include>
</includes>
</configuration>

“

默认包含所有 classes 目录内容，通常只需配置 excludes。

生成测试 JAR（Test JAR）

用于将测试代码打包，供其他模块复用（如共享测试工具类）：

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<goals>
<goal>test-jar</goal>
</goals>
</execution>
</executions>
</plugin>

自定义 JAR 文件名（不推荐）

虽然可通过修改，但强烈建议保持默认命名规则以符合 Maven 约定：

<configuration>
<finalName>my-custom-name</finalName><!-- 生成 my-custom-name.jar -->
</configuration>

完整示例

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.0</version>
<configuration>
<archive>
<!-- 生成的jar中，包含pom.xml和pom.properties这两个文件 -->
<addMavenDescriptor>true</addMavenDescriptor>
<!-- 生成MANIFEST.MF的设置 -->
<manifest>
<!--这个属性特别关键，如果没有这个属性，有时候我们引用的包maven库 下面可能会有多个包，并且只有一个是正确的，其余的可能是带时间戳的， 
    此时会在classpath下面把那个带时间戳的给添加上去，然后我们 在依赖打包的时候，打的是正确的，所以两头会对不上，报错。 -->
<useUniqueVersions>false</useUniqueVersions>
<!-- 为依赖包添加路径, 这些路径会写在MANIFEST文件的Class-Path下 -->
<addClasspath>true</addClasspath>
<!-- 这个jar所依赖的jar包添加classPath的时候的前缀，如果这个jar本身和依赖包在同一级目录，则不需要添加 -->
<classpathPrefix>lib/</classpathPrefix>
<!-- jar启动入口类 -->
<mainClass>com.xf.demo.Test</mainClass>
</manifest>
<manifestEntries>
<!-- 在Class-Path下添加配置文件的路径 -->
<Class-Path>../config/</Class-Path>
<!-- 假如这个项目可能要引入一些外部资源，但是你打包的时候并不想把这些资源文件打进包里面，这个时候你必须在这边额外指定一些这些资源 文件的路径，这个位置指定的话，
        要根据你预期的这些位置去设置，我这边 所有jar都在lib下，资源文件都在config下，lib和config是同级的 同时还需要注意另外一个问题，假如你的pom文件里面配置了 <scope>system</scope>,
        就是你依赖是你本地的资源，这个时候使用这个插件，classPath里面是不会添加，所以你得手动把这个依赖添加进这个地方，用空格隔开就行 -->
</manifestEntries>
</archive>
<!-- jar包的位置 -->
<outputDirectory>${project.build.directory}/lib</outputDirectory>
<includes>
<!-- 打jar包时，打包class文件和config目录下面的 properties文件 -->
<!-- 有时候可能需要一些其他文件，这边可以配置，包括剔除的文件等等 -->
<include>**/*.class</include>
<include>**/*.properties</include>
</includes>
</configuration>
</plugin>

四、常见使用场景

五、与其他插件的关系

• maven-compiler-plugin：先编译 .java → .class，再由 jar-plugin 打包。
• maven-shade-plugin / maven-assembly-plugin：用于构建包含依赖的“胖 JAR”，替代而非增强 jar-plugin。
• maven-source-plugin / maven-javadoc-plugin：分别生成源码包和文档包，与 jar-plugin 并列使用。

六、最佳实践

• 显式声明插件版本（避免隐式继承带来的不确定性）。
• 不要修改 finalName，除非有特殊部署需求。
• 可执行 JAR + 依赖分离：用 jar-plugin 打主 JAR，用 maven-dependency-plugin 复制依赖到 lib/ 目录。
• 测试 JAR 谨慎使用：仅当多个模块共享测试逻辑时才启用。