问题：如何解决Maven Assembly插件打包时依赖冲突？

Question

在使用 Maven Assembly 插件进行项目打包时，常遇到多个依赖版本冲突导致构建失败或运行时异常。该问题通常由不同模块引入的依赖版本不一致引起。解决方法包括：使用 `` 排除冲突依赖、通过 `` 显式控制依赖打包顺序、结合 Maven 的 `exclusion` 标签排除特定传递依赖，或改用 Maven Shade 插件增强依赖合并能力。此外，统一版本管理、合理使用 `` 和 `` 也可减少冲突发生。掌握这些技巧有助于提升构建稳定性和可维护性。

Answer 1

使用 Maven Assembly 插件时依赖版本冲突问题分析与解决策略

在使用 Maven Assembly 插件进行项目打包时，依赖版本冲突是一个常见且棘手的问题。特别是在多模块项目中，不同模块引入的依赖版本不一致，容易导致构建失败或运行时异常。本文将从问题现象出发，逐步深入分析其成因，并提供多种解决方案，帮助开发者提升构建的稳定性与可维护性。

1. 问题现象与初步识别

当使用 Maven Assembly 插件打包时，可能会遇到如下现象：

• 构建失败，提示“class file has wrong version”或“NoSuchMethodError”等错误。
• 运行时抛出异常，如“LinkageError”或“ClassNotFoundException”。
• 依赖库的版本与预期不一致，导致功能异常。

这些问题通常源于多个依赖模块引入了相同库的不同版本，导致打包时版本冲突。

2. 依赖冲突的成因分析

依赖冲突主要来源于以下几种情况：

成因类型	描述
多模块依赖引入不同版本	多个模块各自引入了相同依赖的不同版本。
传递依赖版本不一致	Maven 自动解析依赖树时，不同路径引入的版本不一致。
插件配置不严谨	Assembly 插件未显式控制依赖合并顺序。

3. 解决方案一：使用 <excludes> 排除冲突依赖

可以在 Assembly 插件配置中使用 <excludes> 排除某些版本的依赖，避免其被打包进最终的 jar 包中。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
        <excludes>
            <exclude>com.example:conflict-lib:jar:1.0.0</exclude>
        </excludes>
    </configuration>
</plugin>

4. 解决方案二：通过 <dependencySets> 控制打包顺序

<dependencySets> 允许开发者显式定义哪些依赖被打包，以及它们的顺序。这有助于控制最终 jar 包中的依赖优先级。

<dependencySets>
    <dependencySet>
        <outputDirectory>/</outputDirectory>
        <useProjectArtifact>true</useProjectArtifact>
        <unpack>true</unpack>
        <scope>runtime</scope>
        <includes>
            <include>com.example:preferred-lib</include>
        </includes>
    </dependencySet>
</dependencySets>

5. 解决方案三：Maven 的 <exclusion> 标签

在 pom.xml 中使用 <exclusion> 可以阻止某些传递依赖被引入，从而避免版本冲突。

<dependency>
    <groupId>com.example</groupId>
    <artifactId>some-lib</artifactId>
    <version>2.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.example</groupId>
            <artifactId>conflict-lib</artifactId>
        </exclusion>
    </exclusions>
</dependency>

6. 替代方案：使用 Maven Shade 插件

对于复杂的依赖冲突问题，推荐使用 Maven Shade 插件，它提供了更强大的依赖合并和重命名机制。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.example.Main</mainClass>
                    </transformer>
                </transformers>
                <filters>
                    <filter>
                        <artifact>com.example:conflict-lib</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
        </execution>
    </executions>
</plugin>

7. 预防策略：统一版本管理与合理使用 scope 和 optional

除了事后处理，更应从源头减少冲突发生的可能：

• 统一版本管理：使用 <dependencyManagement> 统一指定依赖版本。
• 合理使用 <scope>：如 test、provided 等作用域避免不必要的依赖打包。
• 使用 <optional>：将某些依赖标记为可选，防止其被其他模块自动引入。

8. 依赖冲突排查流程图（mermaid 格式）

graph TD A[开始构建] --> B{是否出现依赖冲突？} B -- 是 --> C[查看依赖树 mvn dependency:tree] C --> D[定位冲突依赖] D --> E[尝试排除冲突依赖] E --> F{是否解决？} F -- 是 --> G[构建成功] F -- 否 --> H[使用 Shade 插件处理] H --> I[构建成功] B -- 否 --> G