Maven 打包含第三方依賴的可執行 JAR 完整指南

Maven 打包含第三方依賴的可執行 JAR 完整指南

直接執行 mvn package 生成的 JAR 只包含項目自身類，缺少第三方依賴，無法通過 java -jar 直接運行。本文介紹三種主流打包「胖 JAR」方案，並推薦最通用的 Maven Assembly Plugin 配置。

方案一：Maven Assembly Plugin（推薦，最通用）

在 pom.xml 的 <build><plugins> 中添加：

    org.apache.maven.plugins
    maven-assembly-plugin
    3.6.0
    
        
            
                com.example.MainApp 
            
        
        
            jar-with-dependencies
        
    
    
        
            make-assembly
            package
            
                single
            
        
    

執行打包：

mvn clean compile assembly:single
# 或綁定生命周期後直接
mvn clean package

產出：target/xxx-jar-with-dependencies.jar，包含所有依賴，可直接 java -jar 運行。

方案二：Maven Shade Plugin（更適合複雜合併場景）

解決類衝突、重命名包、簽名處理等高級需求：

    org.apache.maven.plugins
    maven-shade-plugin
    3.5.1
    
        
            package
            shade
            
                
                    
                        com.example.MainApp
                    
                
            
        
    

方案三：Spring Boot Maven Plugin（Spring Boot 項目專用）

若是 Spring Boot 項目，直接繼承 spring-boot-starter-parent 或引入插件：

    org.springframework.boot
    spring-boot-maven-plugin
    3.2.0
    
        
            repackage
        
    

執行 mvn package 即生成可執行 Fat JAR，內置類加載器無需解壓依賴。

常見坑點避雷

• 主類未指定：Manifest 中無 Main-Class → no main manifest attribute
• 簽名文件殘留：引入簽名依賴導致 SecurityException → Shade Plugin 添加 DontIncludeResourceTransformer 排除 META-INF/*.SF, *.DSA, *.RSA
• 資源文件覆蓋：多模塊同名配置文件合併 → 使用 AppendingTransformer 合併 spring.factories 等
• JAR 衝突：不同依賴包含同類不同版本 → dependency:tree 排查，exclusion 或 relocation 重命名包

驗證與運行

# 查看 JAR 結構
jar tf target/xxx-jar-with-dependencies.jar | head -20

# 直接運行
java -jar target/xxx-jar-with-dependencies.jar

# 指定主類運行 (無 manifest 時)
java -cp target/xxx-jar-with-dependencies.jar com.example.MainApp

總結： 普通 Java 項目用 Assembly Plugin 最省事；需處理包衝突/簽名用 Shade Plugin；Spring Boot 項目直接用官方插件。記住在 CI/CD 流程中綁定 package 階段，確保構建產物即可部署運行。