本文详细介绍了如何在不依赖ide的情况下，使用maven构建包含本地外部jar库的可执行jar文件。核心解决方案涉及声明`system`范围依赖、利用`maven-dependency-plugin`将本地库复制到目标目录，并通过`maven-jar-plugin`的`manifestentries`配置，将这些库正确添加到生成jar的`class-path`中，确保程序在独立运行时能够找到并加载所有必要的外部依赖。
在Java项目开发中，特别是在没有IDE辅助的情况下，如何将本地的外部JAR库（例如，一些自定义的工具库或特定版本的第三方库）打包进一个可独立运行的Maven项目，并确保其在运行时能够被正确加载，是一个常见的挑战。本文将提供一个详细的教程，指导您如何通过Maven的配置实现这一目标。
1. 项目结构与示例代码
首先，我们假设您有一个主项目（MyApplication）需要依赖一个本地的外部库（testlib.jar）。
主项目（MyApplication）代码示例：
// src/main/java/TEST/App.java
package TEST;
import TEST.Lib; // 假设Lib类在testlib.jar中
public class App {
public static void main( String[] args ) {
new Lib().go();
System.out.println("Application started, attempting to call external lib method.");
}
}外部库（testlib.jar）的源代码示例（假设编译后生成testlib.jar）：
// testlib/src/main/java/TEST/Lib.java
package TEST;
import javax.swing.JFrame;
import javax.swing.JLabel;
public class Lib {
public void go() {
JFrame frame = new JFrame("Test Lib Window");
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
frame.setSize(400,100);
frame.add(new JLabel("Hello from Test Lib!"));
frame.setVisible(true);
}
}为了使MyApplication能够找到testlib.jar，我们通常会在主项目根目录下创建一个libs文件夹，并将testlib.jar放入其中。
项目目录结构示意：
MyApplication/
├── pom.xml
├── src/
│ └── main/
│ └── java/
│ └── TEST/
│ └── App.java
└── libs/
└── testlib.jar2. 配置Maven pom.xml
为了正确地将本地外部库打包并使其可执行，我们需要对pom.xml进行以下关键配置：
2.1 声明本地依赖
首先，在pom.xml的<dependencies>部分声明testlib.jar为本地依赖。使用system范围（scope）和systemPath指向本地JAR文件的相对路径。
<dependencies>
<!-- 其他依赖... -->
<dependency>
<groupId>testlib</groupId>
<artifactId>testlib</artifactId>
<version>1.0</version>
<scope>system</scope>
<systemPath>${project.basedir}/libs/testlib.jar</systemPath>
</dependency>
</dependencies>注意事项：
- groupId和artifactId可以根据实际情况自定义，但要与后续配置保持一致。
- version字段是必需的，Maven在复制依赖时会用到。
- systemPath应使用${project.basedir}来确保路径的相对性和可移植性。
2.2 使用 maven-dependency-plugin 复制依赖
system范围的依赖默认不会被Maven打包到最终的JAR中，也不会自动添加到Class-Path。因此，我们需要使用maven-dependency-plugin将testlib.jar复制到目标（target）目录下的一个子文件夹中，例如lib。
将以下配置添加到<build>部分的<plugins>中：
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.1.2</version> <!-- 推荐使用较新版本 -->
<executions>
<execution>
<id>copy-dependencies</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/lib</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
<!-- maven-jar-plugin 配置将在下一节介绍 -->
</plugins>
</build>配置说明：
- phase: prepare-package阶段确保在打包主JAR之前，依赖已经被复制。
- outputDirectory: 指定依赖将被复制到的目标文件夹，这里是${project.build.directory}/lib，即target/lib。
- overWrite*: 这些配置控制是否覆盖已存在的依赖文件。
2.3 配置 maven-jar-plugin 创建可执行JAR
最后，我们需要配置maven-jar-plugin来创建可执行JAR，并确保在JAR的MANIFEST.MF文件中正确设置Class-Path，使其指向我们刚刚复制的本地库。
将以下配置添加到<build>部分的<plugins>中（与maven-dependency-plugin同级）：
<build>
<plugins>
<!-- maven-dependency-plugin 配置... -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version> <!-- 推荐使用较新版本 -->
<configuration>
<archive>
<manifest>
<mainClass>TEST.App</mainClass>
</manifest>
<manifestEntries>
<!-- 注意：Maven在复制时会将testlib.jar重命名为 testlib-1.0.jar -->
<Class-Path>lib/testlib-1.0.jar</Class-Path>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>配置说明：
- mainClass: 指定您的应用程序的入口类。
- manifestEntries: 这是关键部分。它允许您向JAR的MANIFEST.MF文件添加自定义条目。
- Class-Path: 此条目告诉JVM在哪里查找外部依赖。非常重要的一点是，Maven在复制system范围的依赖时，通常会将其重命名为artifactId-version.jar的形式。因此，如果您的testlib.jar版本是1.0，它将被复制为testlib-1.0.jar。这里的路径lib/testlib-1.0.jar是相对于生成的JAR文件所在目录的路径。
3. 完整的 pom.xml 示例
综合上述配置，您的pom.xml文件将类似于：
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>MyApplication</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<!-- 本地外部库依赖 -->
<dependency>
<groupId>testlib</groupId>
<artifactId>testlib</artifactId>
<version>1.0</version>
<scope>system</scope>
<systemPath>${project.basedir}/libs/testlib.jar</systemPath>
</dependency>
</dependencies>
<build>
<plugins>
<!-- 复制依赖到 target/lib 目录 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.1.2</version>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/lib</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
<!-- 创建可执行JAR并配置Class-Path -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version>
<configuration>
<archive>
<manifest>
<mainClass>TEST.App</mainClass>
</manifest>
<manifestEntries>
<Class-Path>lib/testlib-1.0.jar</Class-Path>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>
</project>4. 构建与运行
在完成pom.xml配置后，您可以通过命令行执行Maven命令来构建项目：
mvn clean package
执行成功后，您会在项目的target目录下找到以下文件和目录：
- MyApplication-1.0-SNAPSHOT.jar (您的主可执行JAR)
- lib/ 目录，其中包含 testlib-1.0.jar
现在，您可以运行您的可执行JAR文件：
java -jar target/MyApplication-1.0-SNAPSHOT.jar
此时，您应该能看到由testlib.jar中的Lib.go()方法创建的Swing窗口。
5. 注意事项与总结
- system Scope的局限性： system范围的依赖通常用于那些无法通过Maven仓库获取的本地JAR文件。它不适合作为常规的、可传递的依赖。在大多数情况下，建议将本地JAR安装到本地Maven仓库 (mvn install:install-file) 或将其发布到私有Maven仓库。
- 依赖命名： 务必注意maven-dependency-plugin复制依赖时，会将其重命名为artifactId-version.jar的形式。在maven-jar-plugin的Class-Path配置中，必须使用这个重命名后的文件名。
- Class-Path的相对路径： Class-Path中的路径是相对于可执行JAR文件本身的。这意味着MyApplication-1.0-SNAPSHOT.jar和lib/testlib-1.0.jar必须位于相同的父目录下才能被正确加载。
- 插件版本： 示例中使用了特定版本的Maven插件。建议使用较新且稳定的版本，以获得更好的兼容性和功能。
- 替代方案（Fat JAR）： 对于更复杂的场景，如果希望将所有依赖都打包到一个独立的JAR文件中（即“胖JAR”或“Uber JAR”），可以考虑使用maven-shade-plugin或spring-boot-maven-plugin。这种方式会将所有依赖的类文件解压并重新打包到主JAR中，避免了外部lib文件夹的需求，但会增加JAR文件的大小。
通过上述步骤，您已经成功地使用Maven构建了一个包含本地外部库的可执行JAR文件，并确保了其在独立运行时的依赖加载。这种方法在特定场景下非常有用，尤其是在没有IDE或需要精细控制打包过程时。
