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

使用Maven构建包含本地外部库的可执行JAR文件教程

霞舞

发布： 2025-10-13 12:12:01

原创

913人浏览过

使用Maven构建包含本地外部库的可执行JAR文件教程

本文详细介绍了如何在不依赖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.jar

登录后复制

2. 配置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>中：

豆包AI编程

豆包推出的AI编程助手

483

查看详情

<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文件的大小。