maven-shade-plugin 入门指南

淩亂°似流年 2021-06-24 15:56 646阅读 0赞

有时候，需要将复杂的项目， 包括各种xml文件属性文件， 类， jar等等打包到一个可以执行的jar包中， 然后用java -jar xxx.jar 来运行项目， 这样简单方便， 特别是在编写一些测试工具时，尤为重要。

但是经常发现打包后的项目无法启动， 其中一大类是您项目有问题， 但是这个相对好解决， 毕竟自己的项目可以在windows下的ide中做各种调试，测试都测试好了， 在打包一般程序问题的概率就低得多了。

1. Why?

通过 maven-shade-plugin 生成一个 uber-jar，它包含所有的依赖 jar 包。

2. Goals


















Goal Description
shade:help Display help information on maven-shade-plugin.Callmvn shade:help -Ddetail=true -Dgoal=<goal-name>to display parameter details.
shade:shade Mojo that performs shading delegating to the Shader component.

3. Usage

  • 配置 maven-shade-plugin

maven-shade-plugin 将 goal shade:shade 绑定到 phase package 上。

  1. <build>
  2.      <plugins>
  3.          <plugin>
  4.              <groupId>org.apache.maven.plugins</groupId>
  5.              <artifactId>maven-shade-plugin</artifactId>
  6.              <version>2.4.3</version>
  7.              <configuration>
  8.                 <!-- put your configurations here -->
  9.              </configuration>
  10.              <executions>
  11.                  <execution>
  12.                      <phase>package</phase>
  13.                      <goals>
  14.                         <goal>shade</goal>
  15.                      </goals>
  16.                  </execution>
  17.              </executions>
  18.          </plugin>
  19.      </plugins>
  20.  </build>

  • 执行命令

    mvn clean package

会在 target 文件生成一个 uber-jar，以 -shaded.jar 为后缀的 jar 包。

4. Examples

  • Selecting Contents for Uber JAR

将该工程依赖的部分 Jar 包 include/exclude 掉。

  1. <build>
  2.     <plugins>
  3.       <plugin>
  4.         <groupId>org.apache.maven.plugins</groupId>
  5.         <artifactId>maven-shade-plugin</artifactId>
  6.         <version>2.4.3</version>
  7.         <executions>
  8.           <execution>
  9.             <phase>package</phase>
  10.             <goals>
  11.               <goal>shade</goal>
  12.             </goals>
  13.             <configuration>
  14.               <artifactSet>
  15.                 <excludes>
  16.                   <exclude>classworlds:classworlds</exclude>
  17.                   <exclude>junit:junit</exclude>
  18.                   <exclude>jmock:*</exclude>
  19.                   <exclude>*:xml-apis</exclude>
  20.                   <exclude>org.apache.maven:lib:tests</exclude>
  21.                   <exclude>log4j:log4j:jar:</exclude>
  22.                 </excludes>
  23.               </artifactSet>
  24.             </configuration>
  25.           </execution>
  26.         </executions>
  27.       </plugin>
  28.     </plugins>
  29. </build>

将依赖的某个 Jar 包内部的类或者资源 include/exclude 掉。

  1. <build>
  2.     <plugins>
  3.       <plugin>
  4.         <groupId>org.apache.maven.plugins</groupId>
  5.         <artifactId>maven-shade-plugin</artifactId>
  6.         <version>2.4.3</version>
  7.         <executions>
  8.           <execution>
  9.             <phase>package</phase>
  10.             <goals>
  11.               <goal>shade</goal>
  12.             </goals>
  13.             <configuration>
  14.               <filters>
  15.                 <filter>
  16.                   <artifact>junit:junit</artifact>
  17.                   <includes>
  18.                     <include>junit/framework/**</include>
  19.                     <include>org/junit/**</include>
  20.                   </includes>
  21.                   <excludes>
  22.                     <exclude>org/junit/experimental/**</exclude>
  23.                     <exclude>org/junit/runners/**</exclude>
  24.                   </excludes>
  25.                 </filter>
  26.                 <filter>
  27.                   <artifact>*:*</artifact>
  28.                   <excludes>
  29.                     <exclude>META-INF/*.SF</exclude>
  30.                     <exclude>META-INF/*.DSA</exclude>
  31.                     <exclude>META-INF/*.RSA</exclude>
  32.                   </excludes>
  33.                 </filter>
  34.               </filters>
  35.             </configuration>
  36.           </execution>
  37.         </executions>
  38.       </plugin>
  39.     </plugins>
  40. </build>

maven-shade-plugin 自动将所有不使用的类全部排除掉，将 uber-jar 最小化。

  1. <build>
  2.     <plugins>
  3.       <plugin>
  4.         <groupId>org.apache.maven.plugins</groupId>
  5.         <artifactId>maven-shade-plugin</artifactId>
  6.         <version>2.4.3</version>
  7.         <executions>
  8.           <execution>
  9.             <phase>package</phase>
  10.             <goals>
  11.               <goal>shade</goal>
  12.             </goals>
  13.             <configuration>
  14.               <minimizeJar>true</minimizeJar>
  15.             </configuration>
  16.           </execution>
  17.         </executions>
  18.       </plugin>
  19.     </plugins>
  20.   </build>
  • Attaching the Shaded Artifact

默认会生成一个Jar包和一个以 “-shaded”为结尾的uber-jar包，可以通过配置来指定uber-jar的后缀名。

  1. <build>
  2.     <plugins>
  3.       <plugin>
  4.         <groupId>org.apache.maven.plugins</groupId>
  5.         <artifactId>maven-shade-plugin</artifactId>
  6.         <version>2.4.3</version>
  7.         <executions>
  8.           <execution>
  9.             <phase>package</phase>
  10.             <goals>
  11.               <goal>shade</goal>
  12.             </goals>
  13.             <configuration>
  14.               <shadedArtifactAttached>true</shadedArtifactAttached>
  15.               <shadedClassifierName>jackofall</shadedClassifierName> <!-- Any name that makes sense -->
  16.             </configuration>
  17.           </execution>
  18.         </executions>
  19.       </plugin>
  20.     </plugins>
  21.   </build>
  • Executable JAR

通过设置 MainClass 创建一个可执行 Jar 包。

  1. <build>
  2.     <plugins>
  3.       <plugin>
  4.         <groupId>org.apache.maven.plugins</groupId>
  5.         <artifactId>maven-shade-plugin</artifactId>
  6.         <version>2.4.3</version>
  7.         <executions>
  8.           <execution>
  9.             <phase>package</phase>
  10.             <goals>
  11.               <goal>shade</goal>
  12.             </goals>
  13.             <configuration>
  14.               <transformers>
  15.                 <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
  16.                   <mainClass>org.sonatype.haven.HavenCli</mainClass>
  17.                 </transformer>
  18.               </transformers>
  19.             </configuration>
  20.           </execution>
  21.         </executions>
  22.       </plugin>
  23.     </plugins>
  24.   </build>
  • Relocating Classes

Java 工程经常会遇到第三方 Jar 包冲突，使用 maven shade plugin 解决 jar 或类的多版本冲突。 maven-shade-plugin 在打包时，可以将项目中依赖的 jar 包中的一些类文件打包到项目构建生成的 jar 包中，在打包的时候把类重命名。下面的配置将 org.codehaus.plexus.util jar 包重命名为 org.shaded.plexus.util。

  1. <build>
  2.     <plugins>
  3.       <plugin>
  4.         <groupId>org.apache.maven.plugins</groupId>
  5.         <artifactId>maven-shade-plugin</artifactId>
  6.         <version>2.4.3</version>
  7.         <executions>
  8.           <execution>
  9.             <phase>package</phase>
  10.             <goals>
  11.               <goal>shade</goal>
  12.             </goals>
  13.             <configuration>
  14.               <relocations>
  15.                 <relocation>
  16.                   <pattern>org.codehaus.plexus.util</pattern>
  17.                   <shadedPattern>org.shaded.plexus.util</shadedPattern>
  18.                   <excludes>
  19.                     <exclude>org.codehaus.plexus.util.xml.Xpp3Dom</exclude>
  20.                     <exclude>org.codehaus.plexus.util.xml.pull.*</exclude>
  21.                   </excludes>
  22.                 </relocation>
  23.               </relocations>
  24.             </configuration>
  25.           </execution>
  26.         </executions>
  27.       </plugin>
  28.     </plugins>
  29.   </build>
  31. -----

下面的部分介绍的更为细致些， 特别是， jar包和类的剔除等

网上有一些maven-shade-plugin替代maven-assembly-plugin的文章，原因是代maven-assembly-plugin打出的jar包中要么是不能设置Main-Class，要么spring的META-INF/spring.*文件相互覆盖了。对于这两个问题，maven-assembly-plugin在当前的版本(3.1.0)中都可以解决了(方法见https://my.oschina.net/u/2377110/blog/1584205)。

实际上这两个插件所针对的用途其实是有差异的，而它们与maven默认的maven-jar-plugin都是打包插件，简单的区别如下：

|plugin|function| | — | — | |maven-jar-plugin|maven 默认打包插件，用来创建 project jar| |maven-shade-plugin|用来打可执行包，包含依赖，以及对依赖进行取舍过滤| |maven-assembly-plugin|支持定制化打包方式，更多是对项目目录的重新组装|

当你只想将项目打成一个可执行包时，maven-shade-plugin非常适合。一般情况下，pom文件中shade插件配置如下。

  1. <build>  
  2.     <plugins>  
  3.         <plugin>  
  4.             <groupId>org.apache.maven.plugins</groupId>  
  5.             <artifactId>maven-shade-plugin</artifactId>  
  6.             <version>1.4</version>  
  7.             <executions>  
  8.                 <execution>  
  9.                     <phase>package</phase>  
  10.                     <goals>  
  11.                         <goal>shade</goal>  
  12.                     </goals>  
  13.                     <configuration>  
  14.                         <filters>  
  15.                             <filter>  
  16.                                 <artifact>*:*</artifact>  
  17.                                 <excludes>  
  18.                                     <exclude>META-INF/*.SF</exclude>  
  19.                                     <exclude>META-INF/*.DSA</exclude>  
  20.                                     <exclude>META-INF/*.RSA</exclude>  
  21.                                 </excludes>  
  22.                             </filter>  
  23.                         </filters>  
  24.                         <transformers>  
  25.                             <transformer  
  26.                                 implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">  
  27.                                 <mainClass>com.lcifn.Application</mainClass>  
  28.                             </transformer>  
  29.                             <transformer  
  30.                                 implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">  
  31.                                 <resource>META-INF/spring.handlers</resource>  
  32.                             </transformer>  
  33.                             <transformer  
  34.                                 implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">  
  35.                                 <resource>META-INF/spring.schemas</resource>  
  36.                             </transformer>  
  37.                         </transformers>  
  38.                     </configuration>  
  39.                 </execution>  
  40.             </executions>  
  41.         </plugin>  
  42.     </plugins>  
  43. </build>

shade插件绑定的是package生命周期目标，并设置com.lcifn.Application为Main-Class，以及将META-INF/spring.*文件合并(追加而非覆盖)，并过滤掉所有依赖的META/INF中SF,DSA,RSA后缀文件。这里涉及到filter配置和transformer配置。

filters和artifactSet

Filter操作在打包时将jar包中的内容排除。它是以groupId:artifactId为标识，在filter内部可以使用/更细致地控制，既可以移除代码文件，也可以移除配置文件。

  1. <!-- 按package过滤junit包 -->
  2. <configuration>
  3.     <filters>
  4.         <filter>
  5.             <artifact>junit:junit</artifact>
  6.             <includes>
  7.                 <include>junit/framework/**</include>
  8.                 <include>org/junit/**</include>
  9.             </includes>
  10.             <excludes>
  11.                 <exclude>org/junit/experimental/**</exclude>
  12.                 <exclude>org/junit/runners/**</exclude>
  13.             </excludes>
  14.         </filter>
  15.     </filters>
  16. </configuration>

如果想将整个jar包都过滤掉，可以使用，也是指定groupId:artifactId的标识。

  1. <configuration>
  2.     <artifactSet>
  3.         <excludes>
  4.             <exclude>classworlds:classworlds</exclude>
  5.             <exclude>junit:junit</exclude>
  6.             <exclude>jmock:*</exclude>
  7.             <exclude>*:xml-apis</exclude>
  8.             <exclude>org.apache.maven:lib:tests</exclude>
  9.             <exclude>log4j:log4j:jar:</exclude>
  10.         </excludes>
  11.     </artifactSet>
  12. </configuration>

另外配置将项目中没有使用的依赖自动移除

  1. <configuration>
  2.     <minimizeJar>true</minimizeJar>
  3. </configuration>

可以和共同使用

  1. <configuration>
  2.     <minimizeJar>true</minimizeJar>
  3.     <filters>
  4.         <filter>
  5.             <artifact>log4j:log4j</artifact>
  6.             <includes>
  7.                 <include>**</include>
  8.             </includes>
  9.         </filter>
  10.         <filter>
  11.             <artifact>commons-logging:commons-logging</artifact>
  12.             <includes>
  13.                 <include>**</include>
  14.             </includes>
  15.         </filter>
  16.     </filters>
  17. </configuration>

资源转换

在打包时，存在将多个构件中的class文件或资源文件聚合的需求。shade插件提供了丰富的Transformer工具类。这里介绍一些常用的Transformer。

ManifestResourceTransformer

往MANIFEST文件中写入Main-Class是可执行包的必要条件。ManifestResourceTransformer可以轻松实现。

  1. <configuration>
  2.     <transformers>
  3.         <transformer
  4.             implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
  5.             <mainClass>com.lcifn.Application</mainClass>
  6.         </transformer>
  7.     </transformers>
  8. </configuration>

AppendingTransformer

用来处理多个jar包中存在重名的配置文件的合并，尤其是spring。

  1. <configuration>
  2.     <transformers>
  3.         <transformer
  4.             implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
  5.             <resource>META-INF/spring.handlers</resource>
  6.         </transformer>
  7.         <transformer
  8.             implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
  9.             <resource>META-INF/spring.schemas</resource>
  10.         </transformer>
  11.     </transformers>
  12. </configuration>

ServicesResourceTransformer

JDK的服务发现机制是基于META-INF/services/目录的，如果同一接口存在多个实现需要合并 ，则可以使用此Transformer。

  1. <configuration>
  2.   <transformers>
  3.     <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
  4.   </transformers>
  5. </configuration>

更多的Transformer见http://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html

原始构件与shade构件

默认情况下，shade插件会覆盖基于项目的jar包，而生成包含所有依赖的jar包。但有时需要原始的jar包和shade后的jar包同时被部署，可以配置如下。

  1. <configuration>
  2.   <shadedArtifactAttached>true</shadedArtifactAttached>
  3.   <!-- 名称会作为后缀在shade构件jar包后 -->
  4.   <shadedClassifierName>jackofall</shadedClassifierName> 
  5. </configuration>

发表评论

表情：
评论列表 （有 0 条评论，646人围观）

还没有评论，来说两句吧...

相关阅读

    相关 GitBook 入门指南

    GitBook 介绍 GitBook 是一款现代化的文档平台，支持团队协作，可以在上面写产品文档、内部知识分享、接口文档等。GitBook 有网页版和本地版两种，网页版地

    ╰+攻爆jí腚メ╰+攻爆jí腚メ/ 0 赞/ 768 阅读

    相关 webpack 入门指南

    什么是 webpack？ webpack是近期最火的一款模块加载器兼打包工具，它能把各种资源，例如JS（含JSX）、coffee、样式（含less/sass）、图片等都作为模

    悠悠悠悠/ 0 赞/ 353 阅读

    相关 Docker入门指南

    Docker是一个开放平台，用以开发、交付和运行应用系统。Docker通过启动轻量级的容器，可以打包发布完整可交付的应用系统。不同的容器之间是互相隔离的。 Docker容器是

    ￡神魔★判官ぃ￡神魔★判官ぃ/ 0 赞/ 428 阅读

    相关 JVM 入门指南

    一、什么是JVM？ JVM： JVM是Java Virtual Machine的缩写，中文翻译为Java虚拟机。JVM 可以看作一台抽象的计算机，如同真实的计算机一样，它

    叁歲伎倆叁歲伎倆/ 0 赞/ 526 阅读