Maven Assembly Plugin 實現自定義打包完整指南

Maven 標準打包（jar/war/ear）無法滿足非標準目錄結構發布需求。Assembly Plugin 是 Maven 官方提供的標準化打包插件，支持任意文件集、依賴集組合，輸出 zip、tar.gz 等格式。本文以實戰項目演示從配置到生成的全過程。

目標打包結構

demo1.zip
├── run.bat / run.sh
├── lib/
│   ├── demo1.jar
│   └── *.jar (runtime 依賴)
├── config/
│   └── *.properties, *.xml
└── log/ (空目錄)

項目目錄佈局

demo1/
├── src/main/java          # Java 源碼
├── src/main/resources     # 打入 jar 的資源
├── src/main/config        # 外部化配置文件
├── src/main/bin           # 啟動腳本
├── src/main/assemble      # Assembly 描述文件
├── src/test/...
├── target/
└── pom.xml

配置 Assembly Plugin (pom.xml)

<build>
  <plugins>
    <plugin>
      <artifactId>maven-assembly-plugin</artifactId>
      <configuration>
        <appendAssemblyId>false</appendAssemblyId> <!-- 不在文件名添加 assembly id -->
        <descriptors>
          <descriptor>src/main/assemble/package.xml</descriptor>
        </descriptors>
      </configuration>
      <executions>
        <execution>
          <id>make-assembly</id>
          <phase>package</phase> <!-- 綁定到 package 階段 -->
          <goals><goal>single</goal></goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Assembly 描述文件 (src/main/assemble/package.xml)

<assembly xmlns="https://maven.apache.org/POM/4.0.0"
          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/assembly-1.0.0.xsd">
  <id>package</id>
  <formats>
    <format>zip</format> <!-- 支持 zip, tar, tar.gz, tar.bz2 -->
  </formats>
  <includeBaseDirectory>true</includeBaseDirectory> <!-- 包含項目名根目錄 -->
  
  <fileSets>
    <!-- bin 目錄 → 根目錄 -->
    <fileSet>
      <directory>src/main/bin</directory>
      <outputDirectory>/</outputDirectory>
    </fileSet>
    <!-- config 目錄 → config/ -->
    <fileSet>
      <directory>src/main/config</directory>
      <outputDirectory>config</outputDirectory>
    </fileSet>
  </fileSets>
  
  <dependencySets>
    <!-- runtime 依賴 → lib/ -->
    <dependencySet>
      <outputDirectory>lib</outputDirectory>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
</assembly>

關鍵配置解析

執行與驗證

# Eclipse: Run As → Maven package
# 命令行:
mvn clean package

# 產物位置:
target/demo1.zip

解壓驗證目錄結構完全符合預期。相比 Maven Ant Task，Assembly Plugin 純聲明式、零腳本、原生集成生命周期，輕快優雅。

進階提示

• 多描述符：<descriptors> 下添加多個 <descriptor> 生成不同發布包。
• 文件過濾：<includes>/<excludes> 控制文件集內容。
• 文件模式：<fileMode>/<directoryMode> 設置 Unix 權限。
• 模塊打包：多模塊項目可用 <moduleSets> 組合子模塊產物。