使用Maven构建包含本地外部库的可执行JAR：一份详细教程-java教程-PHP中文网

使用Maven构建包含本地外部库的可执行JAR：一份详细教程

本教程将指导您如何使用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目录下。

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>

登录后复制

注意事项：

豆包AI编程

豆包推出的AI编程助手

483

查看详情

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。掌握这一技巧，将使您在处理特殊本地依赖时更加灵活和高效。

以上就是使用Maven构建包含本地外部库的可执行JAR：一份详细教程的详细内容，更多请关注php中文网其它相关文章！