本教程详细指导如何在不依赖IDE的情况下，使用Maven构建一个包含本地外部JAR库的可执行JAR文件。通过配置system范围依赖、maven-dependency-plugin复制依赖，以及maven-jar-plugin设置Class-Path清单条目，确保所有必需的本地库都能被正确打包并被JVM在运行时发现，从而解决system范围依赖在可执行JAR中无法加载的问题。
在Java项目开发中，尤其是在不使用集成开发环境（IDE）的情况下，有时需要将本地文件系统中的外部JAR库（例如，一些自定义工具包或不通过Maven仓库发布的库）打包进一个可执行的JAR文件。Maven作为强大的项目管理工具，虽然主要用于管理通过仓库发布的依赖，但通过特定的插件配置，也能很好地处理本地外部库。本教程将详细阐述如何通过Maven的pom.xml配置，实现这一目标。
项目结构与示例代码
为了演示，我们假设有两个Java文件：一个提供简单功能的本地库testlib.jar，另一个是调用该库的主应用程序。
1. 外部库代码 (TEST/Lib.java)
这个代码将被编译并打包成testlib.jar。
package TEST;
import javax.swing.*;
public class Lib {
public void go() {
JFrame frame = new JFrame();
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
frame.setSize(400, 100);
frame.add(new JLabel("Test Lib"));
frame.setVisible(true);
}
}2. 主应用程序代码 (TEST/App.java)
这个应用程序将调用testlib.jar中的go()方法。
package TEST;
public class App {
public static void main(String[] args) {
new Lib().go();
}
}3. 项目目录结构
在您的Maven项目根目录下，创建以下结构：
my-app/
├── pom.xml
├── src/
│ └── main/
│ └── java/
│ └── TEST/
│ └── App.java
└── libs/
└── testlib.jar <-- 您的本地外部库请确保testlib.jar已经存在于libs/目录下。如果尚未生成，您可以使用javac和jar命令手动编译Lib.java并打包：
# 在 my-app/libs/ 目录下创建 Lib.java # javac Lib.java # jar -cvf testlib.jar Lib.class # 或者，在 my-app/ 目录下创建 testlib-src/TEST/Lib.java # cd testlib-src # javac TEST/Lib.java # jar -cvf ../libs/testlib.jar TEST/*.class # cd ..
Maven pom.xml 配置详解
要使Maven能够将本地外部库正确地包含在可执行JAR中，我们需要在pom.xml中进行以下关键配置。
1. 声明本地系统依赖
首先，在pom.xml的<dependencies>部分声明testlib.jar为system范围的依赖。
<dependencies>
<dependency>
<groupId>testlib</groupId>
<artifactId>testlib</artifactId>
<version>1</version>
<scope>system</scope>
<systemPath>${project.basedir}/libs/testlib.jar</systemPath>
</dependency>
</dependencies>- <groupId>、<artifactId>、<version>: 这些是Maven坐标，即使是本地库也需要定义，它们在pom.xml中作为唯一标识符使用。
- <scope>system</scope>: 指示Maven此依赖是系统级别的，不会从Maven仓库下载，而是直接从本地文件系统获取。
- <systemPath>${project.basedir}/libs/testlib.jar</systemPath>: 指定本地JAR文件的绝对路径。${project.basedir}是一个Maven内置变量，代表项目根目录，确保路径的相对性和跨平台兼容性。请使用正斜杠/作为路径分隔符，即使在Windows系统上也是如此。
2. 使用 maven-dependency-plugin 复制依赖
system范围的依赖不会被Maven自动打包到最终的JAR文件中，也不会在默认的Class-Path中引用。为了解决这个问题，我们需要使用maven-dependency-plugin将这些本地库复制到项目构建目录（target）下的一个指定子目录（例如lib）。
<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>
<includeScope>system</includeScope> <!-- 仅复制system scope的依赖 -->
</configuration>
</execution>
</executions>
</plugin>
<!-- ... 其他插件配置 ... -->
</plugins>
</build>- <groupId>、<artifactId>: 插件标识符。
- <version>: 插件版本，建议使用较新且稳定的版本。
-
<execution>: 定义插件的执行阶段。
- <id>copy-dependencies</id>: 执行ID，用于唯一标识此执行。
- <phase>prepare-package</phase>: 指定插件在package阶段之前执行，确保在JAR打包前依赖已被复制。
- <goals><goal>copy-dependencies</goal></goals>: 指定执行copy-dependencies目标。
-
<configuration>: 插件配置。
- <outputDirectory>${project.build.directory}/lib</outputDirectory>: 指定依赖将被复制到的目录。${project.build.directory}通常是target目录。
- <includeScope>system</includeScope>: 这是一个重要配置，它告诉插件只复制system范围的依赖。
3. 配置 maven-jar-plugin 构建可执行JAR并设置 Class-Path
最后，我们需要配置maven-jar-plugin来构建可执行JAR，并在其META-INF/MANIFEST.MF文件中正确设置Main-Class和Class-Path，以便JVM在运行时能够找到外部库。
<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>
<!-- addClasspath 默认会添加所有Maven管理的依赖到Class-Path，但对system scope不直接生效 -->
<!-- <addClasspath>true</addClasspath> -->
</manifest>
<manifestEntries>
<!-- 显式指定本地库的路径，注意Maven会重命名文件为 artifactId-version.jar -->
<Class-Path>lib/testlib-1.jar</Class-Path>
</manifestEntries>
</archive>
</configuration>
</plugin>
</plugins>
</build>- <mainClass>TEST.App</mainClass>: 指定应用程序的入口类。
-
<manifestEntries>: 这是解决问题的关键。它允许您向MANIFEST.MF文件添加自定义条目。
-
<Class-Path>lib/testlib-1.jar</Class-Path>: 此条目告诉JVM在查找类时，除了JAR自身，还要在与JAR同级的lib目录下寻找testlib-1.jar。
- 注意文件名: maven-dependency-plugin在复制依赖时，通常会将文件重命名为artifactId-version.jar的格式。因此，testlib.jar会变成testlib-1.jar（如果版本是1）。请务必根据实际复制后的文件名进行设置。
-
<Class-Path>lib/testlib-1.jar</Class-Path>: 此条目告诉JVM在查找类时，除了JAR自身，还要在与JAR同级的lib目录下寻找testlib-1.jar。
- <addClasspath>true</addClasspath>: 这个配置通常用于Maven管理的（非system范围）依赖，它会根据Maven的依赖解析结果自动生成Class-Path。对于我们手动复制的system范围依赖，需要通过manifestEntries显式指定。为了避免混淆，在此示例中我们将其注释掉，以强调manifestEntries的重要性。
完整的 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>my-app</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<maven.compiler.source>8</maven.compiler.source>
<maven.compiler.target>8</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<!-- 声明本地系统依赖 -->
<dependency>
<groupId>testlib</groupId>
<artifactId>testlib</artifactId>
<version>1</version>
<scope>system</scope>
<systemPath>${project.basedir}/libs/testlib.jar</systemPath>
</dependency>
</dependencies>
<build>
<plugins>
<!-- 插件1: 复制系统依赖到target/lib目录 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.1.2</version>
<executions>
<execution>
<id>copy 
