本教程将指导您如何使用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); } }
我们将这个类编译并打包成testlib.jar，并将其放置在主项目的libs目录下。
立即进入“豆包AI人工智官网入口”；
立即学习“豆包AI人工智能在线问答入口”；
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}来保持路径的相对性。
<dependencies> <dependency> <groupId>testlib</groupId> <artifactId>testlib</artifactId> <version>1.0</version> <scope>system</scope> <systemPath>${basedir}/libs/testlib.jar</systemPath> </dependency> </dependencies>
注意事项：
- systemPath中建议使用正斜杠/而非反斜杠，以确保跨平台兼容性。
- groupId和artifactId可以自定义，但要保持一致性。version也很重要，因为Maven在复制时会用到它。
2. 使用 maven-dependency-plugin 复制本地库
为了让可执行JAR在运行时能够找到testlib.jar，我们需要将其复制到target目录下的一个子目录中（例如target/lib）。maven-dependency-plugin的copy-dependencies目标可以完成此任务。
<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> <!-- 将所有依赖复制到 target/lib 目录下 --> <outputDirectory>${project.build.directory}/lib</outputDirectory> <!-- 允许覆盖已存在的依赖，确保最新 --> <overWriteReleases>true</overWriteReleases> <overWriteSnapshots>true</overWriteSnapshots> <overWriteIfNewer>true</overWriteIfNewer> <!-- 仅复制系统范围的依赖（或其他你需要的范围） --> <includeScope>system</includeScope> </configuration> </execution> </executions> </plugin> <!-- 其他插件，如 maven-jar-plugin 将在此处配置 --> </plugins> </build>
配置说明：
- <phase>prepare-package</phase>：确保在打包之前完成依赖的复制。
- <outputDirectory>${project.build.directory}/lib</outputDirectory>：指定依赖将被复制到target/lib目录。
- <includeScope>system</includeScope>：明确指示只复制system范围的依赖。
3. 配置 maven-jar-plugin 生成可执行JAR
最后一步是配置maven-jar-plugin来生成可执行JAR，并确保MANIFEST.MF中的Class-Path正确指向我们刚刚复制的本地库。
<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> <addClasspath>true</addClasspath> <!-- 确保Maven自动添加其他标准依赖 --> <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>TEST.App</mainClass>：指定应用程序的入口点。
- <manifestEntries>：这是解决问题的核心。在这里，我们手动添加Class-Path条目。
- <Class-Path>lib/testlib-1.0.jar</Class-Path>：
- 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。
<?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>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>${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-dependencies</id> <phase>prepare-package</phase> <goals> <goal>copy-dependencies</goal> </goals> <configuration> <outputDirectory>${project.build.directory}/lib</outputDirectory> <overWriteReleases>true</overWriteReleases> <overWriteSnapshots>true</overWriteSnapshots> <overWriteIfNewer>true</overWriteIfNewer> <includeScope>system</includeScope> </configuration> </execution> </executions> </plugin> <!-- 插件2: 构建可执行JAR并配置 MANIFEST.MF --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>3.3.0</version> <configuration> <archive> <manifest> <addClasspath>true</addClasspath> <mainClass>TEST.App</mainClass> </manifest> <manifestEntries> <!-- 指向复制后的本地JAR文件 --> <Class-Path>lib/testlib-1.0.jar</Class-Path> </manifestEntries> </archive> </configuration> </plugin> </plugins> </build> </project>
构建与运行
-
项目结构准备： 在您的项目根目录下创建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。掌握这一技巧，将使您在处理特殊本地依赖时更加灵活和高效。
评论（已关闭）
评论已关闭