Maven打包进阶：maven-assembly-plugin详解与实践

1. Maven打包与maven-assembly-plugin概述在Java项目开发中Maven作为主流的构建工具其打包功能是项目交付的关键环节。maven-assembly-plugin是Maven生态中用于定制化打包的核心插件它能够将项目输出、依赖项、文档等资源按照特定规则组合成可分发的归档文件。不同于默认的maven-jar-plugin只生成简单JAR包maven-assembly-plugin支持多模块聚合打包依赖项内嵌处理自定义目录结构启动脚本生成多种打包格式zip/tar/war等典型应用场景包括需要包含第三方依赖的fat jar打包交付包含配置文件和文档的完整发布包生成符合特定目录规范的分发包制作包含启动脚本的可执行包2. 核心配置详解2.1 基础POM配置在pom.xml中添加插件声明build plugins plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-assembly-plugin/artifactId version3.3.0/version configuration descriptorRefs descriptorRefjar-with-dependencies/descriptorRef /descriptorRefs archive manifest mainClasscom.example.MainApp/mainClass /manifest /archive /configuration executions execution phasepackage/phase goals goalsingle/goal /goals /execution /executions /plugin /plugins /build关键配置项说明descriptorRefs引用预定义的打包描述符archive/manifest配置MANIFEST.MF文件executions绑定到package生命周期阶段2.2 自定义描述符文件在src/main/assembly目录下创建custom-assembly.xmlassembly xmlnshttp://maven.apache.org/ASSEMBLY/2.1.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/ASSEMBLY/2.1.0 http://maven.apache.org/xsd/assembly-2.1.0.xsd iddistribution/id formats formatzip/format /formats fileSets fileSet directory${project.build.directory}/directory outputDirectory//outputDirectory includes include*.jar/include /includes /fileSet fileSet directorysrc/main/resources/directory outputDirectory/config/outputDirectory /fileSet /fileSets dependencySets dependencySet outputDirectory/lib/outputDirectory scoperuntime/scope /dependencySet /dependencySets /assembly主要配置元素formats定义输出格式zip/tar/tar.gz等fileSets控制文件复制规则dependencySets管理依赖项位置3. 高级应用技巧3.1 多环境打包策略通过profile实现不同环境的差异化打包profiles profile iddev/id build plugins plugin artifactIdmaven-assembly-plugin/artifactId configuration descriptors descriptorsrc/main/assembly/dev-assembly.xml/descriptor /descriptors /configuration /plugin /plugins /build /profile profile idprod/id build.../build /profile /profiles3.2 启动脚本生成使用fileMode和lineEnding控制脚本格式fileSet directorysrc/main/scripts/directory outputDirectory/bin/outputDirectory includes includestartup.sh/include includeshutdown.sh/include /includes fileMode0755/fileMode lineEndingunix/lineEnding /fileSet3.3 依赖项排除与过滤dependencySet outputDirectory/lib/outputDirectory excludes excludeorg.slf4j:slf4j-log4j12/exclude /excludes unpacktrue/unpack unpackOptions excludes excludeMETA-INF/*.SF/exclude /excludes /unpackOptions /dependencySet4. 常见问题排查4.1 依赖冲突解决当出现NoSuchMethodError等依赖问题时使用mvn dependency:tree分析依赖树在dependencySet中添加useProjectArtifactfalse/useProjectArtifact通过excludes排除冲突依赖4.2 资源过滤失效确保资源目录已正确配置过滤resources resource directorysrc/main/resources/directory filteringtrue/filtering /resource /resources4.3 文件权限问题Linux环境下需注意通过fileMode设置文件权限如0755使用directoryMode设置目录权限对于Windows交叉编译添加outputDirectoryMapping处理路径分隔符5. 性能优化建议并行构建配置configuration paralleltrue/parallel threadCount4/threadCount /configuration增量构建技巧为不常变动的模块设置recompressZippedFilesfalse/recompressZippedFiles对大文件使用useStrictFilteringtrue/useStrictFiltering内存调优 在MAVEN_OPTS中添加-XX:MaxPermSize512m -Xmx2048m6. 最佳实践总结目录结构规范/myapp /bin - 启动脚本 /lib - 依赖JAR /config - 配置文件 /docs - 文档版本管理策略在文件名中包含版本号和打包时间使用assembly id区分不同打包类型为SNAPSHOT版本添加时间戳多模块项目打包在父POM中统一管理assembly配置使用moduleSets控制子模块包含规则通过includeSubModulestrue/includeSubModules包含子模块依赖实际项目中我们通常会结合maven-assembly-plugin与maven-shade-plugin前者负责资源整合后者处理依赖冲突和类重定位。对于Spring Boot项目可以考虑使用spring-boot-maven-plugin的repackage功能替代部分assembly场景。