使用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的部分声明testlib.jar为本地依赖。使用system范围（scope）和systemPath指向本地JAR文件的相对路径。


    
    
        testlib
        testlib
        1.0
        system
        ${project.basedir}/libs/testlib.jar

注意事项：

groupId和artifactId可以根据实际情况自定义，但要与后续配置保持一致。
version字段是必需的，Maven在复制依赖时会用到。
systemPath应使用${project.basedir}来确保路径的相对性和可移植性。

2.2 使用 maven-dependency-plugin 复制依赖

system范围的依赖默认不会被Maven打包到最终的JAR中，也不会自动添加到Class-Path。因此，我们需要使用maven-dependency-plugin将testlib.jar复制到目标（target）目录下的一个子文件夹中，例如lib。

将以下配置添加到部分的中：


    
        
            org.apache.maven.plugins
            maven-dependency-plugin
            3.1.2 
            
                
                    copy-dependencies
                    prepare-package
                    
                        copy-dependencies
                    
                    
                        ${project.build.directory}/lib
                        false
                        false
                        true

配置说明：

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，使其指向我们刚刚复制的本地库。

将以下配置添加到部分的中（与maven-dependency-plugin同级）：


    
        
        
            org.apache.maven.plugins
            maven-jar-plugin
            3.3.0 
            
                
                    
                        TEST.App
                    
                    
                        
                        lib/testlib-1.0.jar

配置说明：

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文件将类似于：



    4.0.0

    com.example
    MyApplication
    1.0-SNAPSHOT

    
        1.8
        1.8
        UTF-8
    

    
        
        
            testlib
            testlib
            1.0
            system
            ${project.basedir}/libs/testlib.jar
        
    

    
        
            
            
                org.apache.maven.plugins
                maven-dependency-plugin
                3.1.2
                
                    
                        copy-dependencies
                        prepare-package
                        
                            copy-dependencies
                        
                        
                            ${project.build.directory}/lib
                            false
                            false
                            true
                        
                    
                
            

            
            
                org.apache.maven.plugins
                maven-jar-plugin
                3.3.0
                
                    
                        
                            TEST.App
                        
                        
                            lib/testlib-1.0.jar

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

通过上述步骤，您已经成功地使用Maven构建了一个包含本地外部库的可执行JAR文件，并确保了其在独立运行时的依赖加载。这种方法在特定场景下非常有用，尤其是在没有IDE或需要精细控制打包过程时。