Maven Assembly插件使用与标签详解_Java

一、介绍

assembly 插件的主要作用是，允许用户将项目输出与它的依赖项、模块、站点文档、和其他文件一起组装成一个可分发的归档文件。

二、常见的maven插件

plugin	function
maven-jar-plugin	maven 默认打包插件【springboot默认打包方式】，用来创建 project jar
maven-shade-plugin	用来打可执行包，executable(fat) jar
maven-assembly-plugin	支持定制化打包方式，例如 apache 项目的打包方式

三、使用

1.在pom.xml中引入assembly插件

2.创建assembly.xml

assembly.xml展示

<assembly xmlns="http://maven.apache.org/assembly/2.1.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"
          xsi:schemalocation="http://maven.apache.org/assembly/2.1.0 http://maven.apache.org/xsd/assembly-2.1.0.xsd">

<!-- 编写自定义的assembly文件  -->

</assembly>

四、标签介绍

1.插件引入时的标签介绍

pom.xml

<plugin>
	<groupid>org.apache.maven.plugins</groupid>
    <artifactid>maven-assembly-plugin</artifactid>
    <version>3.3.0</version>
    <executions><!-- 执行器 -->
        <execution>
            <id>make-assembly</id> <!--名字任意 -->   
            <phase>package</phase> <!-- 绑定到package生命周期阶段上 -->
            <goals>
                <goal>single</goal><!-- 只运行一次 -->
            </goals>
            <configuration>
                <finalname>xxx</finalname><!-- 文件名 -->
                <appendassemblyid>{boolean}</appendassemblyid><!-- true：finalname属性值作为打包文件的前缀，assembly文件中的id作为紧随其后的名称；false：不与id连用-->
                <descriptors> <!--描述文件路径-->  
                    <descriptor>src/main/resources/zip.xml</descriptor>  
                </descriptors>  
            </configuration>  
        </execution>
    </executions>
</plugin>

2.assembly.xml中的标签介绍

id

id 标识符，添加到生成文件名称的后缀符。如果指定 id 的话，目标文件则是 ${artifactid}-${id}.tar.gz

结构：

<id>xxx</id>

formats

支持的打包格式

结构：

<formats>
    <format>xxx</format>
</formats>

标签名	值类型	描述
format	string	支持的打包格式，有zip，tar，tar.gz(or tgz)，tar.bz2(or tbz2)，tar.snappy，tar.xz(or txz)，jar，dir，war格式类型

includebasedirectory

默认为true。指定打的包是否包含打包层目录（比如finalname是prefix，当值为true，所有文件被放在包内的prefix目录下，否则直接放在包的根目录下。finalname标签在pom文件中注册插件里面的configuration标签下

结构：

<includebasedirectory>xxx</includebasedirectory>

basedirectory

设置生成的程序集存档的基目录。如果没有设置此参数，并且includebasedirectory == true，则${project.build. path (从2.2.1开始)

结构：

<basedirectory>xxx</basedirectory>

includesitedirectory

默认值：false。在最终的归档文件中包含一个站点目录。项目的站点目录位置由程序集插件的sitedirectory参数确定

结构：

<includesitedirectory>xxxx</includesitedirectory>

containerdescriptorhandlers

常用的文件合并

结构：

<containerdescriptorhandlers>
    <containerdescriptorhandler>
      <handlername/>
      <configuration/>
    </containerdescriptorhandler>
  </containerdescriptorhandlers>

标签名	值类型	描述
containerdescriptorhandler	list	为进入程序集存档的文件配置过滤器，以支持聚合各种类型的描述符片段，如components.xml、web.xml等。
handlername	string	处理程序的plexus角色提示，用于从容器查找
configuration	dom	处理程序的配置选项

提醒：configuration具体配置标签有哪些，官方暂没有提供，网络暂没有找到完整数据，故不展示

modulesets

指定程序集中包含哪些模块文件。 moduleset通过提供一个或多个子元素来指定

结构：

<modulesets>
    <moduleset>
        <useallreactorprojects/>
        <includesubmodules/>
        <includes/>
        <excludes/>
        <sources>
            <usedefaultexcludes/>
            <outputdirectory/>
            <includes/>
            <excludes/>
            <filemode/>
            <directorymode/>
            <filesets>
                <fileset>
                    <usedefaultexcludes/>
                    <outputdirectory/>
                    <includes/>
                    <excludes/>
                    <filemode/>
                    <directorymode/>
                    <directory/>
                    <lineending/>
                    <filtered/>
                    <nonfilteredfileextensions/>
                </fileset>
            </filesets>
            <includemoduledirectory/>
            <excludesubmoduledirectories/>
            <outputdirectorymapping/>
        </sources>
        <binaries>
            <outputdirectory/>
            <includes/>
            <excludes/>
            <filemode/>
            <directorymode/>
            <attachmentclassifier/>
            <includedependencies/>
            <dependencysets>
                <dependencyset>
                    <outputdirectory/>
                    <includes/>
                    <excludes/>
                    <filemode/>
                    <directorymode/>
                    <usestrictfiltering/>
                    <outputfilenamemapping/>
                    <unpack/>
                    <unpackoptions>
                        <includes/>
                        <excludes/>
                        <filtered/>
                        <nonfilteredfileextensions/>
                        <lineending/>
                        <usedefaultexcludes/>
                        <encoding/>
                    </unpackoptions>
                    <scope/>
                    <useprojectartifact/>
                    <useprojectattachments/>
                    <usetransitivedependencies/>
                    <usetransitivefiltering/>
                </dependencyset>
            </dependencysets>
            <unpack/>
            <unpackoptions>
                <includes/>
                <excludes/>
                <filtered/>
                <nonfilteredfileextensions/>
                <lineending/>
                <usedefaultexcludes/>
                <encoding/>
            </unpackoptions>
            <outputfilenamemapping/>
        </binaries>
    </moduleset>
</modulesets>

标签名	值类型	描述
moduleset	moduleset	一个或多个项目存在于项目的pml .xml中。这允许您包含属于项目的的源代码或二进制文件。
useallreactorprojects	boolean	默认为false。为true，则该插件将包含当前反应器中用于处理的所有项目。这些将受到包括/排除规则的约束（从2.2开始）
includesubmodules	boolean	默认true。如果设置为false，插件将从这个模块集的处理中排除子模块。否则，它将处理所有子模块，每个子模块都要包含/排除规则。 (从2.2.1开始)
includes/include*	list	包含哪些
excludes/exclude*	list	排除哪些
source	modulesources	插件将在结果程序集中包含该集合中包含的模块的源文件
binaries	modulebinaries	插件将在结果程序集中包含该集合中包含的模块的二进制文件

source

包含用于在程序集中包含项目模块的源文件的配置选项。

标签名	值类型	描述
usedefaultexcludes	boolean	默认为true。在计算受此集合影响的文件时，是否应该使用标准排除模式，比如匹配cvs和subversion元数据文件的那些模式。
outputdirectory	string	相对于程序集的根目录的根设置输出目录。例如，“log”将把指定的文件放到log目录中。
includes/include*	list	包含哪些
excludes/exclude*	list	排除哪些
filemode	string	默认值为0644。类似于unix权限，设置包含的文件的文件模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如:“0644”表示“用户读写”、“组”和“其他只读”。
directorymode	string	默认值为0755。类似于unix权限，设置包含目录的目录模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如，0755表示“用户读写”、“组”和“其他只读”。
filesets/fileset	list	指定要将每个包含模块中的哪些文件组包含在程序集中。通过提供一个或多个子元素来指定文件集
includemoduledirectory	boolean	默认值为true。指定是否应该将模块的finalname前缀到应用于它的任何文件集的outputdirectory值
excludesubmoduledirectories	boolean	默认值为true。指定当前模块下的子模块目录是否应从应用于该模块的文件集中排除。如果你只是想复制与这个moduleset匹配的模块列表的源代码，忽略(或单独处理)存在于当前目录下的模块，这可能是有用的。
outputdirectorymapping	string	default value is: ${module.artifactid}。设置此程序集中包含的所有模块基目录的映射模式。注意:该字段仅在includemoduledirectory == true时使用

binaries

包含用于在程序集中包含项目模块的二进制文件的配置选项

标签名	值类型	描述
outputdirectory	string	相对于程序集的根目录的根设置输出目录
includes/include*	list	包含哪些
excludes/exclude*	list	排除哪些
filemode	string	默认值为0644。类似于unix权限，设置包含的文件的文件模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如:“0644”表示“用户读写”、“组”和“其他只读”。
directorymode	string	默认值为0755。类似于unix权限，设置包含目录的目录模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如，0755表示“用户读写”、“组”和“其他只读”。
attachmentclassifier	string	当指定时，attachmentclassifier将导致组装人员查看附加到模块的工件，而不是主项目工件。如果它能找到匹配指定分类器的附加工件，它将使用它; 否则，它将抛出异常
includedependencies	boolean	默认值为true。如果设置为true，插件将包含这里包含的项目模块的直接和过渡依赖关系。否则，它将只包含模块包。
dependencysets/dependencyset	list	指定要包含在程序集中的模块的哪些依赖项。 dependencyset可以通过提供一个或多个子元素来指定
unpack	boolean	默认值为true。如果设置为true，此属性将把所有模块包解压到指定的输出目录。当设置为false时，模块包将作为存档文件(jar)包含。
unpackoptions	unpackoptions	允许对从模块工件解包的项指定包含和排除，以及过滤选项
outputfilenamemapping	string	设置此程序集中包含的所有非unpacked依赖关系的映射模式。（由于2.2-beta-2; 2.2-beta-1使用${artifactid} - ${version} ${dashclassifier？}。${extension}作为默认值）注意：如果dependencyset指定unpack == true，则outputfilenamemapping将不要使用; 在这些情况下，使用outputdirectory。有关可用于outputfilenamemapping参数的条目的更多详细信息，请参阅插件faq。默认值是：${module.artifactid} - ${module.version} ${dashclassifier？}.${module.extension}。

unpackoptions

指定包含/排除/过滤从存档中提取的项的选项

标签名	值类型	描述
includes/include*	list	包含哪些
excludes/exclude*	list	排除哪些
filtered	boolean	默认值为false。是否使用构建配置中的属性，在文件从归档文件解压缩时过滤文件中的符号
nonfilteredfileextensions/nonfilteredfileextension*	list	附加的文件扩展名不应用过滤
lineending	string	设置文件的行结束符。 (从2.2开始)有效值：“keep” -保留所有行尾； “unix” -使用unix风格的行结束符；“lf” -使用单行换行结束符；“dos” -使用dos风格的行结尾；“crlf” -使用回车，换行
usedefaultexcludes	boolean	默认值为true。在计算受此集合影响的文件时，是否应该使用标准排除模式，比如匹配cvs和subversion元数据文件的那些模式。对于向后兼容性，默认值为true。
encoding	string	允许指定在解压缩存档时使用的编码，对于支持指定编码的解压缩存档。如果未指定，将使用archiver默认值。归档文件默认值通常表示正常(现代)的值。

filesets

管理一组文件的存放位置

结构：

<filesets>
    <fileset>
        <usedefaultexcludes/>
        <outputdirectory/>
        <includes/>
        <excludes/>
        <filemode/>
        <directorymode/>
        <directory/>
        <lineending/>
        <filtered/>
        <nonfilteredfileextensions/>
    </fileset>
</filesets>

标签名	值类型	描述
usedefaultexcludes	boolean	默认值为true。在计算受此集合影响的文件时，是否应该使用标准排除模式，比如匹配cvs和subversion元数据文件的那些模式。对于向后兼容性，默认值为true。
outputdirectory	string	指定文件集合的输出目录，该目录是相对于根目录
includes/include*	list	包含文件
excludes/exclude*	list	排除文件
filemode	string	默认值为0644。类似于unix权限，设置包含的文件的文件模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如:“0644”表示“用户读写”、“组”和“其他“只读。
directorymode	string	默认值为0755。类似于unix权限，设置包含目录的目录模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如，0755表示“用户读写”、“组”和“其他”只读。
directory	string	设置模块目录中的绝对或相对位置。例如，"src/main/bin"会选择定义依赖项的项目的这个子目录
lineending	string	设置文件的行结束符。 (从2.2开始)有效值：“keep” -保留所有行尾； “unix” -使用unix风格的行结束符；“lf” -使用单行换行结束符；“dos” -使用dos风格的行结尾；“crlf” -使用回车，换行
filtered	boolean	默认值为false。是否使用构建配置中的属性在复制文件时过滤符号
nonfilteredfileextensions/nonfilteredfileextension*	list	附加的文件扩展名不应用过滤

files

可以指定目的文件名到指定目录，其他和 filesets 相同

结构：

<files>
    <file>
        <source/>
        <sources/>
        <outputdirectory/>
        <destname/>
        <filemode/>
        <lineending/>
        <filtered/>
    </file>
</files>

标签名	值类型	描述
source	string	源文件，相对路径或绝对路径
sources/source*	list	组合并包含在程序集中的模块文件目录中的绝对或相对路径集
outputdirectory	string	输出目录
destname	string	设置目标文件名。 default与源文件的名称相同
filemode	string	默认值为0644。类似于unix权限，设置包含的文件的文件模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如:“0644”表示“用户读写”、“组”和“其他只读”。
lineending	string	设置文件的行结束符。 (从2.2开始)有效值：“keep” -保留所有行尾； “unix” -使用unix风格的行结束符；“lf” -使用单行换行结束符；“dos” -使用dos风格的行结尾；“crlf” -使用回车，换行
filtered	boolean	设置是否过滤文件

dependencysets

用来定制工程依赖 jar 包的打包方式

结构：

<dependencysets>
    <dependencyset>
        <outputdirectory/>
        <includes/>
        <excludes/>
        <filemode/>
        <directorymode/>
        <usestrictfiltering/>
        <outputfilenamemapping/>
        <unpack/>
        <unpackoptions>
            <includes/>
            <excludes/>
            <filtered/>
            <nonfilteredfileextensions/>
            <lineending/>
            <usedefaultexcludes/>
            <encoding/>
        </unpackoptions>
        <scope/>
        <useprojectartifact/>
        <useprojectattachments/>
        <usetransitivedependencies/>
        <usetransitivefiltering/>
    </dependencyset>
</dependencysets>

标签名	值类型	描述
outputdirectory	string	指定包依赖目录，该目录是相对于根目录
includes/include*	list	包含依赖
excludes/exclude*	list	排除依赖
filemode	string	默认值为0644。类似于unix权限，设置包含的文件的文件模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如:“0644”表示“用户读写”、“组”和“其他只读”。
directorymode	string	设置文件的行结束符。 (从2.2开始)有效值：“keep” -保留所有行尾； “unix” -使用unix风格的行结束符；“lf” -使用单行换行结束符；“dos” -使用dos风格的行结尾；“crlf” -使用回车，换行
usestrictfiltering	boolean	默认值为true。如果指定为true，那么在程序集创建过程中任何用于过滤实际构件的包含/排除模式都将导致构建失败，并显示错误。这是为了强调过时的包含或排除，或者表示程序集描述符配置不正确。（从2.2开始）
outputfilenamemapping	string	设置此程序集中包含的所有非unpacked依赖关系的映射模式。（由于2.2-beta-2; 2.2-beta-1使用${artifactid} - ${version} ${dashclassifier？}。${extension}作为默认值）注意：如果dependencyset指定unpack == true，则outputfilenamemapping将不要使用; 在这些情况下，使用outputdirectory。有关可用于outputfilenamemapping参数的条目的更多详细信息，请参阅插件faq。默认值是：${module.artifactid} - ${module.version} ${dashclassifier？}.${module.extension}。
unpack	boolean	默认为false。如果设置为true，此属性将把所有依赖项解压缩到指定的输出目录中。当设置为false时，依赖项将被包含为存档(jar)。只能解压jar, zip, tar.gz和tar.gz。 bz。
unpackoptions	unpackoptions	允许对从依赖项工件解包的项指定包含和排除，以及过滤选项。
scope	string	默认为runtime。设置这个dependencyset的依赖范围
useprojectartifact	boolean	默认为true。确定当前项目生成期间生成的工件是否应包含在此依赖项集中
useprojectattachments	boolean	默认为false。确定是否应将当前项目生成期间产生的附加构件包括在此依赖项集中
usetransitivedependencies	boolean	默认为true。确定是否将传递依赖项包含在当前依赖项集的处理中。如果为真，包含/排除/usetransitivefiltering将应用于除了主项目依赖工件之外的可传递依赖工件。如果为false, usetransitivefiltering是无意义的，并且包含/排除只会影响项目的直接依赖关系
usetransitivefiltering	boolean	默认为false。确定此依赖项集中的包含/排除模式是否将应用于给定工件的传递路径。如果为真，并且当前工件是由另一个匹配包含或排除模式的工件引入的传递依赖项，那么当前工件也将应用相同的包含/排除逻辑。默认情况下，该值为false，以保持与版本2.1的向后兼容性。这意味着包含/排除只直接应用于当前工件，而不应用于引入它的工件的传递集。

repositories

指定程序集中包含哪些存储库文件。通过提供一个或多个子元素来指定存储库

结构：

<repositories>
    <repository>
        <outputdirectory/>
        <includes/>
        <excludes/>
        <filemode/>
        <directorymode/>
        <includemetadata/>
        <groupversionalignments>
            <groupversionalignment>
                <id/>
                <version/>
                <excludes/>
            </groupversionalignment>
        </groupversionalignments>
        <scope/>
    </repository>
</repositories>

repository

定义要包含在程序集中的maven存储库。可以包含在存储库中的构件是项目的依赖构件。创建的存储库包含所需的元数据条目，还包含sha1和md5校验和。这对于创建将部署到内部存储库的存档非常有用。

注意：目前，只允许来自中央存储库的工件。

标签名	值类型	描述
outputdirectory	string	指定包依赖目录，该目录是相对于根目录
includes/include*	list	当出现子元素时，它们定义一组要包含的工件坐标。如果不存在，则<包括>表示所有有效值。工件坐标可以以简单的groupid:artifactid形式给出，也可以以groupid:artifactid:type[:classifier]:version形式完全限定。此外，还可以使用通配符，如:maven-
excludes/exclude*	list	当出现子元素时，它们定义一组要排除的依赖构件坐标。如果不存在任何排除，则<排除>表示没有排除。工件坐标可以以简单的groupid:artifactid形式给出，也可以以groupid:artifactid:type[:classifier]:version形式完全限定。此外，还可以使用通配符，如:maven-
filemode	string	默认值为0644。类似于unix权限，设置包含的文件的文件模式。这是一个八进制值。格式:(user)(group)(other)，其中每个组件都是read = 4, write = 2, execute = 1的和。例如:“0644”表示“用户读写”、“组”和“其他只读”。
directorymode	string	设置文件的行结束符。 (从2.2开始)有效值：“keep” -保留所有行尾； “unix” -使用unix风格的行结束符；“lf” -使用单行换行结束符；“dos” -使用dos风格的行结尾；“crlf” -使用回车，换行
includemetadata	boolean	默认为true。如果设置为true，该属性将触发存储库元数据的创建，从而允许将存储库用作功能性远程存储库。
groupversionalignments	list	指定要将一组工件与指定的版本保持一致。通过提供一个或多个子元素来指定groupversionalignment。
scope	string	默认为runtime。指定此存储库中包含的工件的范围

groupversionalignment

允许一组工件与指定的版本对齐

标签名	值类型	描述
id	string	您希望为其对齐版本的工件的groupid
version	string	要将此组对齐到的版本
excludes/exclude*	list	当出现子元素时，它们定义要排除的工件的artifactid。如果不存在任何排除，则<排除>表示没有排除。通过提供一个或多个子元素来指定排除

componentdescriptors

指定要包含在程序集中的共享组件xml文件位置。指定的位置必须相对于描述符的基位置。如果描述符是通过类路径中的元素找到的，那么它指定的任何组件也会在类路径中找到。如果它是通过元素的路径名找到的，这里的值将被解释为相对于项目basedir的路径。当找到多个componentdescriptors时，它们的内容将被合并。查看描述符组件以了解更多信息。 componentdescriptor是通过提供一个或多个子元素来指定的

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持代码网。

Maven Assembly插件使用与标签详解

2026年03月06日 • Java •我要评论