maven-assembly-plugin插件怎么使用

发布时间：2022-09-28 11:34:15 作者：iii
来源：亿速云阅读：160

# Maven-Assembly-Plugin插件怎么使用

## 一、插件概述

### 1.1 什么是maven-assembly-plugin
`maven-assembly-plugin`是Maven生态中用于构建项目分发包的核心插件，它能够将项目输出、依赖项、文档等资源按照自定义规则打包成多种格式的归档文件（如ZIP、TAR、JAR等）。该插件名称中的"assembly"意为"装配"，形象地描述了其将项目各组成部分组装成完整分发包的功能。

### 1.2 典型应用场景
- 生成包含所有依赖的**可执行JAR包**（fat-jar）
- 创建包含配置文件的**生产部署包**
- 构建包含文档、脚本的**完整发行包**
- 制作多模块项目的**聚合安装包**
- 生成符合特定目录结构的**平台专用包**

## 二、基础配置

### 2.1 插件引入
在pom.xml中添加插件声明：

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <version>3.6.0</version>
            <configuration>
                <!-- 基础配置 -->
            </configuration>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>single</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2.2 核心配置参数

参数名	说明	示例值
`<finalName>`	输出文件名称	`myapp-${version}`
`<appendAssemblyId>`	是否在文件名追加assembly id	`true`
`<descriptors>`	自定义描述文件路径	`src/assembly/dist.xml`
`<formats>`	打包格式列表	`<format>zip</format>`

三、描述文件详解

3.1 描述文件结构

Assembly描述文件通常放在src/assembly目录下，基本结构如下：

<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">
    <id>dist</id>
    <formats>
        <format>zip</format>
    </formats>
    <!-- 其他配置 -->
</assembly>

3.2 文件集(fileSets)配置

控制项目资源的包含规则：

<fileSets>
    <!-- 包含编译输出 -->
    <fileSet>
        <directory>${project.build.outputDirectory}</directory>
        <outputDirectory>/lib</outputDirectory>
    </fileSet>
    
    <!-- 包含配置文件 -->
    <fileSet>
        <directory>src/main/resources</directory>
        <outputDirectory>/conf</outputDirectory>
        <includes>
            <include>*.properties</include>
        </includes>
    </fileSet>
</fileSets>

3.3 依赖集(dependencySets)配置

管理项目依赖的打包方式：

<dependencySets>
    <!-- 主依赖包 -->
    <dependencySet>
        <outputDirectory>/lib</outputDirectory>
        <scope>runtime</scope>
    </dependencySet>
    
    <!-- 排除测试依赖 -->
    <dependencySet>
        <outputDirectory>/test-lib</outputDirectory>
        <scope>test</scope>
        <excludes>
            <exclude>junit:junit</exclude>
        </excludes>
    </dependencySet>
</dependencySets>

四、高级功能

4.1 环境差异化打包

通过Maven属性实现环境区分：

<fileSets>
    <fileSet>
        <directory>src/main/env/${env}</directory>
        <outputDirectory>/conf</outputDirectory>
    </fileSet>
</fileSets>

执行时指定环境参数：

mvn package -Denv=prod

4.2 动态文件过滤

使用<filtering>标签启用变量替换：

<fileSet>
    <directory>src/main/config</directory>
    <outputDirectory>/conf</outputDirectory>
    <filtered>true</filtered>
</fileSet>

在配置文件中使用Maven属性：

db.url=${db.url}

4.3 自定义格式扩展

支持扩展打包格式（需实现相应Handler）：

<formats>
    <format>zip</format>
    <format>tar.gz</format>
    <format>custom</format>
</formats>

五、典型配置案例

5.1 可执行Fat-Jar配置

<assembly>
    <id>fatjar</id>
    <formats>
        <format>jar</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <dependencySets>
        <dependencySet>
            <unpack>true</unpack>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
    <containerDescriptorHandlers>
        <containerDescriptorHandler>
            <handlerName>metaInf-services</handlerName>
        </containerDescriptorHandler>
    </containerDescriptorHandlers>
</assembly>

5.2 完整发行包配置

<assembly>
    <id>full-dist</id>
    <formats>
        <format>zip</format>
        <format>tar.gz</format>
    </formats>
    <fileSets>
        <fileSet>
            <directory>target</directory>
            <outputDirectory>/</outputDirectory>
            <includes>
                <include>*.jar</include>
            </includes>
        </fileSet>
        <fileSet>
            <directory>src/main/scripts</directory>
            <outputDirectory>/bin</outputDirectory>
            <fileMode>0755</fileMode>
        </fileSet>
    </fileSets>
    <dependencySets>
        <dependencySet>
            <outputDirectory>/lib</outputDirectory>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
</assembly>

六、常见问题排查

6.1 依赖冲突解决

当出现依赖冲突时，可以使用<excludes>过滤特定依赖：

<dependencySet>
    <excludes>
        <exclude>commons-logging:commons-logging</exclude>
    </excludes>
</dependencySet>

6.2 文件重复问题

通过<useStrictFiltering>开启严格模式：

<assembly>
    <useStrictFiltering>true</useStrictFiltering>
    <!-- 其他配置 -->
</assembly>

6.3 性能优化建议

尽量使用<include>/<exclude>缩小文件范围
对大文件启用<useDefaultExcludes>false</useDefaultExcludes>
避免在大型项目中使用<unpack>true</unpack>

七、最佳实践

7.1 目录结构规范

推荐的标准目录布局：

/myapp
  /bin    - 启动脚本
  /conf   - 配置文件
  /lib    - 依赖库
  /logs   - 日志目录（需运行时创建）

7.2 多环境支持方案

使用不同的assembly描述文件
通过Maven profile激活不同配置
结合build-helper-maven-plugin实现条件装配

7.3 版本管理策略

建议在打包时包含构建信息：

<finalName>${project.artifactId}-${project.version}-${maven.build.timestamp}</finalName>

八、与其他插件对比

插件名称	特点	适用场景
maven-shade-plugin	支持类重定位	解决依赖冲突
spring-boot-maven-plugin	专为Spring Boot优化	Spring应用打包
maven-jar-plugin	基础JAR打包	简单库文件打包

九、总结

maven-assembly-plugin作为Maven生态中最灵活的打包工具，通过本文介绍的： 1. 基础配置方法 2. 描述文件编写技巧 3. 高级功能应用 4. 典型问题解决方案

开发者可以构建出满足各种复杂需求的分发包。建议在实际项目中根据具体需求组合使用不同的配置策略，并建立统一的打包规范。

注意：本文基于maven-assembly-plugin 3.x版本编写，部分配置在旧版本中可能不适用 “`

这篇技术文档包含了： 1. 完整的插件使用指南 2. 详细的配置示例 3. 实际应用场景 4. 问题排查方法 5. 最佳实践建议 6. 与其他工具的对比

总字数约2700字，采用标准的Markdown格式，包含代码块、表格等元素，适合作为技术文档发布。

​maven-assembly-plugin插件怎么使用