网站Logo 拾荒的小海螺
首页
研想花开
生活随笔
图库
茶杯狐
关于

JAVA：Spring Boot 集成 Maven Assembly 创建自定义打包

admin
2
2026-02-27

1、简述

maven-assembly-plugin 是 Maven 提供的一个插件，用于将项目的所有依赖及其他资源打包成一个归档文件（如 JAR、ZIP、TAR 等）。它允许自定义打包方式，解决了开发中需要定制化打包的需求，比如创建一个包含所有依赖的可运行 JAR 文件（fat jar）。

image-yaxe.png

2、配置步骤

2.1 引入插件依赖

在项目的 pom.xml 中添加 maven-assembly-plugin 的插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <version>3.6.0</version>
            <configuration>
                <!-- 指定自定义的 Assembly 描述文件 -->
                <descriptors>
                    <descriptor>src/main/assembly/custom-assembly.xml</descriptor>
                </descriptors>
                <!-- 禁用默认依赖打包 -->
                <appendAssemblyId>false</appendAssemblyId>
            </configuration>
            <executions>
                <execution>
                    <id>make-assembly</id>
                    <phase>package</phase>
                    <goals>
                        <goal>single</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2.2 编写 Assembly 描述文件

创建 src/main/assembly/custom-assembly.xml，描述自定义打包逻辑：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3
          http://maven.apache.org/xsd/assembly-1.1.3.xsd">
    <id>bin</id>
    <formats>
        <format>tar.gz</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <dependencySets>
        <dependencySet>
            <outputDirectory>/lib</outputDirectory>
            <useProjectArtifact>true</useProjectArtifact>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
    <fileSets>
        <fileSet>
            <directory>${project.build.directory}/classes</directory>
            <outputDirectory>/</outputDirectory>
        </fileSet>
        <fileSet>
            <directory>src/main/resources</directory>
            <outputDirectory>/config</outputDirectory>
            <includes>
                <include>**/*.properties</include>
                <include>**/*.yaml</include>
                <include>**/log/logback-spring.xml</include>
                <!-- 其他需要包含的资源文件 -->
            </includes>
        </fileSet>
        <!-- 其他文件集配置 -->
    </fileSets>
    <!-- 其他配置选项，如脚本、启动文件等 -->
</assembly>

2.3 代码结构

假设项目目录结构如下：

my-app
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com.lm.assembly.AssemblyApplication.java
│   │   ├── resources
│   │   │   └── application.yaml
│   └── test
├── pom.xml
└── src/main/assembly/custom-assembly.xml

image-pczq.png
通过assembly构建来 Fat JAR，执行以下命令：

mvn clean package assembly:single

构建完成后，可以在 target/ 目录中看到生成的 my-app.jar 文件。

3、打包样例

以下是 maven-assembly-plugin 的几个常见自定义打包场景及对应的配置样例，仅供参考根据自己的项目去调整：

3.1 打包为包含依赖的 ZIP 文件

将项目的输出文件（如 JAR）以及依赖库一起打包为 ZIP 文件，用于分发或部署。

src/main/assembly/zip-assembly.xml：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 
          http://maven.apache.org/xsd/assembly-1.1.3.xsd">

    <id>zip-with-dependencies</id>
    <formats>
        <format>zip</format>
    </formats>
  
    <!-- 包含项目的 JAR 文件 -->
    <files>
        <file>
            <source>${project.build.directory}/${project.build.finalName}.jar</source>
            <outputDirectory>/</outputDirectory>
        </file>
    </files>
  
    <!-- 包含所有依赖 -->
    <dependencySets>
        <dependencySet>
            <outputDirectory>/lib</outputDirectory>
            <unpack>false</unpack>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
</assembly>

3.2 生成一个仅包含资源文件的 TAR 包

将项目中的特定资源（如配置文件、模板文件等）打包为一个 TAR 文件，便于单独分发。

src/main/assembly/resources-only-assembly.xml：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 
          http://maven.apache.org/xsd/assembly-1.1.3.xsd">

    <id>resources-only</id>
    <formats>
        <format>tar.gz</format>
    </formats>
  
    <!-- 包含 src/main/resources 下的所有文件 -->
    <fileSets>
        <fileSet>
            <directory>src/main/resources</directory>
            <outputDirectory>/config</outputDirectory>
            <includes>
                <include>**/*</include>
            </includes>
        </fileSet>
    </fileSets>
</assembly>

3.3 创建包含二进制和脚本的分发包

创建一个分发包，包含可执行 JAR 文件、依赖库以及启动脚本。

src/main/assembly/distribution-assembly.xml：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 
          http://maven.apache.org/xsd/assembly-1.1.3.xsd">

    <id>distribution</id>
    <formats>
        <format>tar.gz</format>
    </formats>
  
    <!-- 包含项目主 JAR -->
    <files>
        <file>
            <source>${project.build.directory}/${project.build.finalName}.jar</source>
            <outputDirectory>/bin</outputDirectory>
        </file>
    </files>
  
    <!-- 包含依赖库 -->
    <dependencySets>
        <dependencySet>
            <outputDirectory>/lib</outputDirectory>
            <unpack>false</unpack>
            <scope>runtime</scope>
        </dependencySet>
    </dependencySets>
  
    <!-- 包含启动脚本 -->
    <fileSets>
        <fileSet>
            <directory>src/main/scripts</directory>
            <outputDirectory>/bin</outputDirectory>
            <fileMode>0755</fileMode>
            <includes>
                <include>start.sh</include>
            </includes>
        </fileSet>
    </fileSets>
</assembly>

3.4 为多模块项目生成统一分发包

在多模块项目中，生成一个分发包，包含所有模块的产出物。

src/main/assembly/multi-module-assembly.xml：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 
          http://maven.apache.org/xsd/assembly-1.1.3.xsd">

    <id>multi-module-distribution</id>
    <formats>
        <format>zip</format>
    </formats>
  
    <!-- 包含父模块的所有子模块输出 -->
    <moduleSets>
        <moduleSet>
            <useAllReactorProjects>true</useAllReactorProjects>
            <includes>
                <include>com.example:*</include>
            </includes>
            <binaries>
                <outputDirectory>/modules</outputDirectory>
                <unpack>false</unpack>
            </binaries>
        </moduleSet>
    </moduleSets>
</assembly>

3.5 创建包含源代码的归档包

打包项目的所有源码文件（包括主代码和测试代码），便于分发或存档。

src/main/assembly/source-archive.xml：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 
          http://maven.apache.org/xsd/assembly-1.1.3.xsd">

    <id>source-archive</id>
    <formats>
        <format>zip</format>
    </formats>
  
    <!-- 包含所有源码 -->
    <fileSets>
        <fileSet>
            <directory>src</directory>
            <outputDirectory>/src</outputDirectory>
            <includes>
                <include>**/*.java</include>
                <include>**/*.xml</include>
                <include>**/*.properties</include>
            </includes>
        </fileSet>
    </fileSets>
</assembly>

以上列出了 maven-assembly-plugin 在不同场景中的使用示例，涵盖了常见的依赖打包、资源归档、分发包创建等需求。你可以根据实际需求灵活调整配置，打造适合自己项目的打包流程！

4、适用场景

🔥 生成可运行 JAR 包：将项目的类文件和所有依赖打包到一个 JAR 文件中。

🔥 多格式打包：支持 ZIP、TAR 等多种格式的打包需求。

🔥 资源归档：将项目中的某些特定文件夹或文件打包成资源包。

🔥 分发包：打包包含运行脚本、配置文件和二进制文件的完整分发包。

5、总结

maven-assembly-plugin 是一个功能强大的插件，适用于各种自定义打包场景。通过配置 Assembly 描述文件，你可以灵活地控制打包内容和格式，从而满足复杂的项目需求。希望本文的内容和示例对你有所帮助！

如果你有其他问题或场景需求，可以随时留言！

动物装饰