Maven 常见问题

xml

1.2 传递性依赖版本冲突（依赖仲裁）

现象
项目依赖 A 和 B，而 A 内部依赖 C:1.0，B 依赖 C:2.0，最终运行时长出 NoSuchMethodError 或 ClassNotFoundException。

原因
Maven 的依赖仲裁机制选择了较老的版本（最近优先 / 第一声明优先），导致某些功能不可用。

解决方案

1. 使用 mvn dependency:tree 查看依赖树，定位冲突。
2. 在 pom.xml 中显式声明所需版本，Maven 会优先使用直接依赖的版本：

   <dependency>
     <groupId>com.example</groupId>
     <artifactId>C</artifactId>
     <version>2.0</version>
   </dependency>
   

3. 排除传递依赖：如果确定不需要某个传递依赖，在声明 A 时将其排除。

   <dependency>
     <groupId>com.example</groupId>
     <artifactId>A</artifactId>
     <exclusions>
       <exclusion>
         <groupId>com.example</groupId>
         <artifactId>C</artifactId>
       </exclusion>
     </exclusions>
   </dependency>
   

4. 使用 dependencyManagement 统一管理版本，让所有传递依赖使用同一版本。

1.3 依赖范围（scope）导致运行期缺失

现象
编译正常，但运行或打包后提示找不到类，依赖的 scope 被标注为 provided、test 或 system。

原因
provided 表示由 JDK 或容器提供，打包时不会包含；test 仅在测试时有效；system 需要手动指定路径且不参与传递。

解决方案

• 确认依赖的 scope 是否合理。若需要在运行期存在，应将 scope 设为 compile（默认）或 runtime。
• system 范围的依赖需配合 systemPath 使用，且不推荐在可移植的项目中使用。

2. 构建与打包问题

2.1 编译版本与 JDK 不匹配

现象
mvn compile 报错诸如 无效的目标发行版: 17 或 source 1.5 中不支持 lambda 表达式。

原因
Maven 默认使用 JDK 1.5 编译；或者 pom.xml 中配置的 maven-compiler-plugin 版本与本地 JDK 不一致。

解决方案
在 pom.xml 中显式配置 Java 版本（推荐统一配置在 properties 中）：

<properties>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
</properties>

或者配置 maven-compiler-plugin：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.11.0</version>
  <configuration>
    <source>17</source>
    <target>17</target>
  </configuration>
</plugin>

最后检查 IDE 和系统环境变量中实际使用的 JDK 版本是否与配置一致。

2.2 资源文件未被打包或乱码

现象
src/main/resources 下的 .xml、.properties 文件没有出现在 target/classes 中，或中文注释变成乱码。

原因
资源过滤（filtering）配置不当，或未指定资源文件的编码方式。

解决方案

1. 如果启用了 filtering，请确认资源目录已正确声明：

   <resources>
     <resource>
       <directory>src/main/resources</directory>
       <filtering>true</filtering>
     </resource>
   </resources>
   

   并将对应属性值在 pom.xml 的 <properties> 或 profile 中定义。
2. 指定编码防止乱码：

   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   </properties>
   

   或者在 maven-resources-plugin 中设置 <encoding>UTF-8</encoding>。

2.3 打包后 JAR 无法运行（没有主清单属性）

现象
运行 java -jar target/xxx.jar 时报错：no main manifest attribute, in xxx.jar。

原因
没有在 JAR 的 MANIFEST.MF 中指定 Main-Class。

解决方案
使用 maven-jar-plugin 配置 Main-Class，或直接使用 maven-assembly-plugin / spring-boot-maven-plugin 构建可执行 JAR。
若为普通 JAR：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <version>3.3.0</version>
  <configuration>
    <archive>
      <manifest>
        <mainClass>com.example.Main</mainClass>
      </manifest>
    </archive>
  </configuration>
</plugin>

若为 Spring Boot 项目，请添加：

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>

2.4 测试被跳过但希望执行

现象
mvn test 没有执行任何测试，控制台显示 Tests are skipped.

原因
pom.xml 中配置了 -DskipTests、-Dmaven.test.skip=true 或在插件中设置了 <skip>true</skip>。

解决方案

1. 检查 Maven 命令是否携带了 -DskipTests 或 -Dmaven.test.skip=true，去掉即可。
2. 查看 pom.xml 中 maven-surefire-plugin 配置是否写死了跳过测试：

   <plugin>
     <artifactId>maven-surefire-plugin</artifactId>
     <configuration>
       <skip>true</skip>   <!-- 移除或改为 false -->
     </configuration>
   </plugin>