本教程将指导您如何使用maven构建一个包含本地外部jar库的可执行jar文件，无需依赖集成开发环境（ide）。我们将通过配置`pom.xml`中的`maven-dependency-plugin`来复制本地库，并利用`maven-jar-plugin`在`manifest.mf`中正确设置`class-path`，确保运行时能够找到并加载这些本地依赖，从而解决直接构建时外部库无法识别的问题。
在Java项目开发中，我们经常需要引入第三方库。对于Maven项目，这些库通常通过Maven中央仓库或私有仓库进行管理。然而，有时我们会遇到需要引入本地文件系统中的JAR包作为依赖的情况，例如一些定制的、未发布到Maven仓库的内部库。当尝试将此类项目打包成可执行JAR时，仅仅声明system范围的依赖并不能保证这些本地库在运行时被正确加载。本文将详细阐述如何通过Maven的插件配置，优雅地解决这一问题。
示例场景：一个简单的Swing应用
为了更好地说明问题，我们构建两个简单的Java程序：一个提供Swing窗口的库testlib.jar，以及一个调用该库的应用程序。
1. 库项目 (testlib.jar)
假设我们有一个名为Lib的类，它创建一个简单的Swing窗口。 Lib.java:
package TEST;
import javax.swing.JFrame;
import javax.swing.JLabel;
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);
}
}
frame.setSize(400, 100);
frame.add(new JLabel("Test Lib"));
frame.setVisible(true);
}
}我们将这个类编译并打包成testlib.jar，并将其放置在主项目的libs目录下。
2. 主应用程序
主应用程序App调用testlib.jar中的Lib.go()方法。 App.java:
package TEST;
public class App {
public static void main(String[] args) {
new Lib().go();
}
}核心挑战分析：为什么直接构建会失败？
当我们将testlib.jar声明为system范围的依赖，并尝试使用maven-jar-plugin生成可执行JAR时，往往会发现运行时抛出NoClassDefFoundError或ClassNotFoundException。这是因为：
- system范围依赖的特性： system范围的依赖主要用于编译阶段，告诉编译器在哪里找到所需的类。Maven在打包时，并不会自动将这些system范围的JAR文件复制到最终的JAR包内部，也不会将其添加到MANIFEST.MF的Class-Path中。
- maven-jar-plugin的addClasspath与classpathPrefix： 尽管maven-jar-plugin提供了addClasspath和classpathPrefix配置项，但它们主要用于处理Maven从远程仓库解析并复制到target/lib目录下的依赖。对于我们手动放置在libs目录下的system范围依赖，这些配置项无法自动将其纳入可执行JAR的Class-Path。
- MANIFEST.MF的Class-Path： Java虚拟机在执行可执行JAR时，会读取其MANIFEST.MF文件中的Class-Path条目来查找外部依赖。如果本地库没有被正确地添加到这个Class-Path中，JVM自然无法找到它们。
解决方案步骤
解决这个问题的关键在于两个步骤：首先，使用maven-dependency-plugin将本地依赖复制到target目录下的指定位置；其次，使用maven-jar-plugin在MANIFEST.MF中手动指定正确的Class-Path。
1. 声明本地依赖 (system scope)
在pom.xml中，首先需要声明testlib.jar为system范围的依赖。请确保systemPath指向本地testlib.jar的正确相对或绝对路径。建议使用${basedir}来保持路径的相对性。
testlib testlib1.0 system ${basedir}/libs/testlib.jar
注意事项：
- systemPath中建议使用正斜杠/而非反斜杠\，以确保跨平台兼容性。
- groupId和artifactId可以自定义，但要保持一致性。version也很重要，因为Maven在复制时会用到它。
2. 使用 maven-dependency-plugin 复制本地库
为了让可执行JAR在运行时能够找到testlib.jar，我们需要将其复制到target目录下的一个子目录中（例如target/lib）。maven-dependency-plugin的copy-dependencies目标可以完成此任务。
org.apache.maven.plugins maven-dependency-plugin3.1.2 copy-dependencies prepare-package copy-dependencies ${project.build.directory}/lib true true true system
配置说明：
-
prepare-package ：确保在打包之前完成依赖的复制。 -
${project.build.directory}/lib ：指定依赖将被复制到target/lib目录。 -
system ：明确指示只复制system范围的依赖。
3. 配置 maven-jar-plugin 生成可执行JAR
最后一步是配置maven-jar-plugin来生成可执行JAR，并确保MANIFEST.MF中的Class-Path正确指向我们刚刚复制的本地库。
org.apache.maven.plugins maven-jar-plugin3.3.0 true TEST.App lib/testlib-1.0.jar
配置说明：
ainClass>TEST.App：指定应用程序的入口点。 ：这是解决问题的核心。在这里，我们手动添加Class-Path条目。 -
lib/testlib-1.0.jar ：- lib/：这是maven-dependency-plugin复制依赖的目标目录，相对于可执行JAR的路径。
- testlib-1.0.jar：非常重要！ maven-dependency-plugin在复制system范围的JAR时，通常会将其重命名为artifactId-version.jar的格式。因此，testlib.jar会变为testlib-1.0.jar。请务必根据您的groupId、artifactId和version来确定最终的文件名。
完整的 pom.xml 配置示例
将上述所有配置整合到pom.xml中，您将得到一个完整的配置，能够成功构建包含本地外部库的可执行JAR。
4.0.0 com.example my-app1.0-SNAPSHOT 1.8 1.8 UTF-8 testlib testlib1.0 system ${basedir}/libs/testlib.jar org.apache.maven.plugins maven-dependency-plugin3.1.2 copy-dependencies prepare-package copy-dependencies ${project.build.directory}/lib true true true system org.apache.maven.plugins maven-jar-plugin3.3.0 true TEST.App lib/testlib-1.0.jar
构建与运行
-
项目结构准备： 在您的项目根目录下创建libs文件夹，并将testlib.jar放入其中。
my-app/ ├── pom.xml ├── src/ │ └── main/ │ └── java/ │ └── TEST/ │ └── App.java └── libs/ └── testlib.jar -
执行Maven构建： 打开命令行或终端，导航到项目根目录（my-app），然后执行Maven的clean install命令：
mvn clean install
这将编译您的项目，运行maven-dependency-plugin复制testlib.jar到target/lib，然后运行maven-jar-plugin生成可执行JAR。
-
运行可执行JAR： 构建成功后，在target目录下会生成my-app-1.0-SNAPSHOT.jar以及一个lib文件夹，其中包含testlib-1.0.jar。 您可以通过以下命令运行它：
java -jar target/my-app-1.0-SNAPSHOT.jar
此时，您应该能看到由testlib.jar创建的Swing窗口成功显示。
注意事项
- 路径分隔符： 在systemPath中使用正斜杠/是最佳实践，因为它在所有操作系统上都能正常工作。
- Class-Path的精确性： MANIFEST.MF中的Class-Path条目必须精确匹配Maven复制后的文件名（包括版本号）和相对路径。任何拼写错误或版本不匹配都将导致运行时错误。
- 版本管理： 尽量避免在生产环境中使用system范围的依赖。更好的做法是将本地库安装到本地Maven仓库（mvn install:install-file ...）或部署到私有Maven仓库，然后像普通依赖一样引用它们。
- 胖JAR（Fat JAR）解决方案： 如果您希望将所有依赖（包括本地依赖）都打包到一个单独的JAR文件中，可以考虑使用maven-shade-plugin或maven-assembly-plugin。这些插件可以将所有依赖的代码提取并合并到主JAR中，或者将所有依赖JAR打包到主JAR内部的特定目录，并自动配置Class-Path。这对于简化部署非常有用，但会使JAR文件变大。
总结
通过本教程，我们学习了如何使用maven-dependency-plugin和maven-jar-plugin协同工作，成功构建一个包含本地外部JAR库的可执行Maven项目。关键在于理解system范围依赖的局限性，并手动配置Maven插件来复制这些本地库，同时在MANIFEST.MF中正确指定其Class-Path。掌握这一技巧，将使您在处理特殊本地依赖时更加灵活和高效。
