使用Maven打包包含本地外部依赖的可执行JAR教程

本教程详细指导如何在不依赖ide的情况下，使用maven构建包含本地外部jar库的可执行jar文件。通过配置`maven-dependency-plugin`复制本地依赖到目标目录，并精确设置`maven-jar-plugin`的`class-path`清单条目，确保运行时能正确加载所有外部类，从而解决本地系统依赖在打包后无法被识别的问题。

在Java项目开发中，尤其是在不使用集成开发环境（IDE）的命令行环境下，管理项目依赖并将其打包成可执行的JAR文件是一项常见任务。当项目依赖于本地文件系统中的外部JAR库时，Maven的默认配置可能无法正确地将这些本地依赖包含进最终的可执行JAR中，导致运行时出现NoClassDefFoundError等问题。本教程将详细介绍如何通过配置Maven的pom.xml文件，解决这一挑战，确保您的项目能够成功打包并运行。

我们将通过以下三个核心步骤来完成此任务：定义本地系统依赖、复制依赖到目标目录以及配置可执行JAR插件。

1. 定义本地系统依赖

首先，您需要在pom.xml文件中声明对本地外部JAR库的依赖。这通过system和标签实现，它告诉Maven该依赖位于本地文件系统而非远程仓库。

假设您的项目有一个名为testlib.jar的本地库，位于项目根目录下的libs文件夹中。

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

说明：

• 、和：这些是Maven坐标，即使是本地依赖也需要提供，它们在构建过程中用于唯一标识该依赖。
• system：指定此依赖是系统范围的，Maven不会尝试从远程仓库下载它。
• ：指向本地JAR文件的绝对路径。${basedir}是一个Maven属性，代表项目根目录，这样可以保持路径的相对性和可移植性。

2. 复制依赖到目标目录

仅仅声明本地依赖并不能将其自动包含到最终的JAR文件中。为了让可执行JAR在运行时能够找到这些本地库，我们需要将它们复制到生成JAR文件旁边的特定目录中。maven-dependency-plugin插件可以帮助我们完成此操作。

将以下插件配置添加到pom.xml的部分：

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

说明：

• 和：指定maven-dependency-plugin。
• prepare-package：将此插件的执行绑定到Maven的prepare-package生命周期阶段，确保在打包主JAR文件之前完成依赖的复制。
• goal>copy-dependencies：指定执行copy-dependencies目标，将所有声明的依赖复制到指定目录。
• ${project.build.directory}/lib：这是关键配置，它指示插件将所有依赖复制到项目的target/lib目录中。lib目录的名称可以自定义，但需要与后续maven-jar-plugin中的Class-Path配置保持一致。
• overWrite*配置：控制是否覆盖已存在的依赖文件。

执行mvn clean package命令后，您会在target目录下看到一个lib文件夹，其中包含了testlib-1.jar（注意Maven会自动在文件名中添加版本号）。

3. 配置可执行JAR插件

最后一步是配置maven-jar-plugin来生成可执行JAR文件，并确保其MANIFEST.MF文件中包含正确的Class-Path条目，指向我们刚刚复制到target/lib目录中的本地依赖。

将以下插件配置添加到pom.xml的部分：

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

说明：

• ainClass>：指定您应用程序的入口点类，例如TEST.App。
• ：此部分允许您向JAR的MANIFEST.MF文件添加自定义条目。
• lib/testlib-1.jar：这是解决问题的核心。它明确告诉JVM在加载主JAR时，到相对于主JAR文件同级的lib目录中寻找testlib-1.jar。请注意，这里的testlib-1.jar是Maven根据依赖的artifactId和version自动生成的名称。如果您的testlib版本是1.0，则可能是testlib-1.0.jar。请务必核对target/lib目录中实际生成的文件名。

完整pom.xml示例

综合以上所有配置，一个完整的pom.xml示例如下：

    4.0.0

    com.example
    my-app
    1.0-SNAPSHOT

    
        8
        8
        UTF-8
    

    
        
        
            testlib
            testlib
            1
            system
            ${basedir}/libs/testlib.jar
        
        
        
            junit
            junit
            4.11
            test
        
    

    
        
            
            
                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.2.0
                
                    
                        
                            TEST.App
                        
                        
                            lib/testlib-1.jar
                        
                    
                
            
        
    

注意事项

1. 依赖版本命名： Maven在复制依赖时，通常会将JAR文件重命名为artifactId-version.jar的格式。例如，testlib.jar（版本1）会被复制为testlib-1.jar。在maven-jar-plugin的Class-Path中，您必须使用这个带版本号的名称。
2. lib目录结构： 生成的可执行JAR文件（例如my-app-1.0-SNAPSHOT.jar）和lib目录（包含testlib-1.jar）将位于target目录下。运行JAR时，这两个文件必须保持相对位置不变。
3. 运行可执行JAR： 完成上述配置并执行mvn clean package后，您可以在命令行中通过以下命令运行生成的JAR：

   java -jar target/my-app-1.0-SNAPSHOT.jar

   请确保在运行命令时，当前目录或JAR文件路径正确。

总结

通过上述步骤，您已经学会了如何使用Maven在不依赖IDE的情况下，成功打包一个包含本地外部JAR库的可执行JAR文件。核心在于利用maven-dependency-plugin将本地依赖复制到指定目录，并通过maven-jar-plugin的manifestEntries配置，在JAR的MANIFEST.MF文件中明确指定这些依赖的Class-Path，从而确保JVM在运行时能够正确找到并加载它们。这种方法提供了一种灵活且强大的方式来管理和部署包含复杂本地依赖的Java应用程序。