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

本教程详细指导如何在不依赖IDE的情况下，使用Maven构建一个包含本地外部JAR库的可执行JAR文件。通过配置system范围依赖、maven-dependency-plugin复制依赖，以及maven-jar-plugin设置Class-Path清单条目，确保所有必需的本地库都能被正确打包并被JVM在运行时发现，从而解决system范围依赖在可执行JAR中无法加载的问题。

在Java项目开发中，尤其是在不使用集成开发环境（IDE）的情况下，有时需要将本地文件系统中的外部JAR库（例如，一些自定义工具包或不通过Maven仓库发布的库）打包进一个可执行的JAR文件。Maven作为强大的项目管理工具，虽然主要用于管理通过仓库发布的依赖，但通过特定的插件配置，也能很好地处理本地外部库。本教程将详细阐述如何通过Maven的pom.xml配置，实现这一目标。

项目结构与示例代码

为了演示，我们假设有两个Java文件：一个提供简单功能的本地库testlib.jar，另一个是调用该库的主应用程序。

1. 外部库代码 (TEST/Lib.java)

这个代码将被编译并打包成testlib.jar。

package TEST;

import javax.swing.*;

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);
    }
}

2. 主应用程序代码 (TEST/App.java)

这个应用程序将调用testlib.jar中的go()方法。

package TEST;

public class App {
    public static void main(String[] args) {
        new Lib().go();
    }
}

3. 项目目录结构

在您的Maven项目根目录下，创建以下结构：

my-app/
├── pom.xml
├── src/
│   └── main/
│       └── java/
│           └── TEST/
│               └── App.java
└── libs/
    └── testlib.jar  <-- 您的本地外部库

请确保testlib.jar已经存在于libs/目录下。如果尚未生成，您可以使用javac和jar命令手动编译Lib.java并打包：

# 在 my-app/libs/ 目录下创建 Lib.java
# javac Lib.java
# jar -cvf testlib.jar Lib.class
# 或者，在 my-app/ 目录下创建 testlib-src/TEST/Lib.java
# cd testlib-src
# javac TEST/Lib.java
# jar -cvf ../libs/testlib.jar TEST/*.class
# cd ..

Maven pom.xml 配置详解

要使Maven能够将本地外部库正确地包含在可执行JAR中，我们需要在pom.xml中进行以下关键配置。

1. 声明本地系统依赖

首先，在pom.xml的部分声明testlib.jar为system范围的依赖。

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

• 、、: 这些是Maven坐标，即使是本地库也需要定义，它们在pom.xml中作为唯一标识符使用。
• system: 指示Maven此依赖是系统级别的，不会从Maven仓库下载，而是直接从本地文件系统获取。
• ${project.basedir}/libs/testlib.jar: 指定本地JA

  

  R文件的绝对路径。${project.basedir}是一个Maven内置变量，代表项目根目录，确保路径的相对性和跨平台兼容性。请使用正斜杠/作为路径分隔符，即使在Windows系统上也是如此。

2. 使用 maven-dependency-plugin 复制依赖

system范围的依赖不会被Maven自动打包到最终的JAR文件中，也不会在默认的Class-Path中引用。为了解决这个问题，我们需要使用maven-dependency-plugin将这些本地库复制到项目构建目录（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
                        system 
                    
                
            
        
        
    

• 、: 插件标识符。
• : 插件版本，建议使用较新且稳定的版本。
• : 定义插件的执行阶段。
  • copy-dependencies: 执行ID，用于唯一标识此执行。
  • prepare-package: 指定插件在package阶段之前执行，确保在JAR打包前依赖已被复制。
  • copy-dependencies: 指定执行copy-dependencies目标。
  • : 插件配置。
    • ${project.build.directory}/lib: 指定依赖将被复制到的目录。${project.build.directory}通常是target目录。
    • system: 这是一个重要配置，它告诉插件只复制system范围的依赖。

3. 配置 maven-jar-plugin 构建可执行JAR并设置 Class-Path

最后，我们需要配置maven-jar-plugin来构建可执行JAR，并在其META-INF/MANIFEST.MF文件中正确设置Main-Class和Class-Path，以便JVM在运行时能够找到外部库。

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

• TEST.App: 指定应用程序的入口类。
• : 这是解决问题的关键。它允许您向MANIFEST.MF文件添加自定义条目。
  • lib/testlib-1.jar: 此条目告诉JVM在查找类时，除了JAR自身，还要在与JAR同级的lib目录下寻找testlib-1.jar。
    • 注意文件名: maven-dependency-plugin在复制依赖时，通常会将文件重命名为artifactId-version.jar的格式。因此，testlib.jar会变成testlib-1.jar（如果版本是1）。请务必根据实际复制后的文件名进行设置。
• true: 这个配置通常用于Maven管理的（非system范围）依赖，它会根据Maven的依赖解析结果自动生成Class-Path。对于我们手动复制的system范围依赖，需要通过manifestEntries显式指定。为了避免混淆，在此示例中我们将其注释掉，以强调manifestEntries的重要性。

完整的 pom.xml 示例

将上述所有配置整合到您的pom.xml中，如下所示：

    4.0.0

    com.example
    my-app
    1.0-SNAPSHOT

    
        8
        8
        UTF-8
    

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

    
        
            
            
                org.apache.maven.plugins
                maven-dependency-plugin
                3.1.2
                
                    
                        copy