Gradle到Maven项目迁移实战：Spring Boot项目构建工具转换指南

1. 从Gradle到Maven：一个老项目的转型之路

最近在整理一个几年前用Gradle构建的遗留项目，准备将其迁移到公司统一的技术栈——Maven上。这听起来像是个简单的格式转换，但真正动手时才发现，从build.gradle到pom.xml的转变，远不止是语法层面的替换。它涉及到依赖管理的哲学差异、插件生态的适配、构建生命周期的重新理解，以及团队协作习惯的调整。如果你也正面临类似的迁移需求，无论是为了统一构建工具、简化CI/CD流程，还是因为某些依赖在Maven仓库中更稳定，这篇基于我实际踩坑经验的图文详解，或许能帮你避开不少弯路。整个过程，我会以一个典型的Spring Boot Web项目为例，带你一步步走完转换、验证和优化的全过程。

2. 转换前的核心准备：理解差异与清理环境

在动手修改任何一行代码之前，充分的准备是成功迁移的一半。这个阶段的目标不是执行转换，而是为转换创造一个干净、可回溯的起点。

2.1 剖析Gradle与Maven的核心差异

很多人把转换想得太简单，以为找个工具自动生成pom.xml就完事了。但如果不理解底层差异，生成的配置文件很可能无法工作，或者埋下隐患。

首先，依赖声明的粒度不同。Gradle的依赖配置（implementation,api,compileOnly,runtimeOnly等）非常精细，旨在优化编译类路径和运行时类路径，这对构建性能有帮助。而Maven主要依赖<scope>来管理，常见的有compile（默认）、provided、runtime、test。在转换时，你需要进行映射：

• Gradle的implementation-> Maven的compilescope（最常用）。
• compileOnly->providedscope（依赖仅用于编译，不会打包）。
• runtimeOnly->runtimescope（仅用于运行时，编译时不需要）。
• testImplementation->testscope。

其次，多模块项目的结构迥异。Gradle的多模块通过在settings.gradle中include子项目，并在子项目的build.gradle中通过dependencies { implementation project(‘:module-a’) }来声明模块依赖。Maven则通过父pom.xml中的<modules>标签聚合子模块，子模块通过<parent>标签继承父POM，模块间依赖使用普通的<dependency>声明，但groupId和artifactId指向兄弟模块。这个结构转换需要手动调整目录和POM文件。

再者，插件和自定义任务。Gradle的插件应用（apply plugin: ‘java’）和自定义Task（task customTask { … }）是其强大灵活性的体现。Maven没有直接对应的“任务”概念，其功能主要通过插件（<plugins>）及其目标（<goals>）来实现。复杂的Gradle自定义任务可能需要用Maven插件重写，或者借助maven-antrun-plugin执行一些Shell/命令，但这往往是迁移中最棘手的部分。

注意：对于简单的项目，自动转换工具可以处理基础依赖。但对于使用了复杂Gradle插件（如特定版本的Android插件、ShadowJar打包插件）或大量自定义构建逻辑的项目，自动转换基本会失败，必须手动分析和重写。

2.2 为当前Gradle项目创建“快照”

在开始转换前，务必确保你的Gradle项目处于一个“干净”且可构建的状态。这为你提供了回滚基准和对照验证的源头。

1. 清理并构建：在项目根目录下，执行./gradlew clean build（Windows下为gradlew.bat clean build）。确保构建成功，没有测试失败（除非是预期内的）。这验证了项目当前是健康的。
2. 生成依赖报告：使用Gradle命令生成依赖树，这对于后续核对Maven依赖版本至关重要。

   ./gradlew dependencies > gradle_dependencies.txt ./gradlew dependencies --configuration runtimeClasspath > gradle_runtime_dependencies.txt

   第一个命令生成所有配置的依赖，信息量巨大。第二个命令生成运行时类路径的依赖，这通常是你最终打包进应用jar/war的依赖集合，是转换核对的重点。
3. 备份关键文件：除了整个项目代码使用Git备份（确保已提交所有更改）外，建议单独复制出关键的Gradle配置文件：
   • build.gradle(或build.gradle.kts)
   • settings.gradle
   • gradle.properties
   • gradle/wrapper/gradle-wrapper.properties（记录了Gradle版本）

这个“快照”能让你在转换过程中迷茫时，随时回头查看Gradle原本是如何做的。

3. 执行转换：从build.gradle到pom.xml

这是迁移的核心操作阶段。我们将采用“工具辅助生成 + 人工校对优化”的策略，而不是完全手动编写POM。

3.1 使用gradle init进行基础转换

从Gradle 6.0开始，gradle init命令支持将现有项目转换为Maven项目。这是最官方的起点。

1. 在项目根目录打开终端或命令行。
2. 执行转换命令：

   ./gradlew init --type pom

   或者，如果你系统安装了全局Gradle：

   gradle init --type pom

3. 命令执行后，Gradle会在当前目录生成一个基本的pom.xml文件。重要提示：这个命令不会删除你原有的Gradle文件，它只是新增了一个POM文件。

然而，根据我的经验，这个自动生成的pom.xml通常非常基础，它主要做了以下几件事：

• 根据项目目录名和gradle.properties中的信息，设置<groupId>,<artifactId>,<version>。
• 将build.gradle中声明的依赖，尝试转换为Maven的<dependency>，并使用compilescope。
• 设置源码编码为UTF-8。
• 添加maven-compiler-plugin并指定Java版本。

它不会处理：

• 多模块项目结构。
• 复杂的依赖配置（如exclude、force版本、自定义源）。
• 任何插件和构建逻辑。
• 资源文件过滤等配置。

所以，生成的pom.xml只是一个粗糙的毛坯房，我们需要把它装修成能住的房子。

3.2 手动完善与校对pom.xml

打开生成的pom.xml，我们开始进行深度加工。下面是一个从Spring Boot Gradle项目转换后，初步完善的pom.xml示例：

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <!-- 1. 坐标信息：根据你的项目修改 --> <groupId>com.example</groupId> <artifactId>my-springboot-app</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>jar</packaging> <!-- 如果是web项目，可能是war --> <!-- 2. 父POM：对于Spring Boot项目，继承官方starter-parent是最佳实践 --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <!-- 请匹配你Gradle项目中的Spring Boot版本 --> <relativePath/> <!-- 从仓库查找，不继承本地 --> </parent> <properties> <java.version>11</java.version> <!-- 与Gradle中sourceCompatibility一致 --> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <!-- 可以在这里统一管理依赖版本，类似于Gradle的ext或version catalog --> <lombok.version>1.18.30</lombok.version> </properties> <dependencies> <!-- Spring Boot Starter Web --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <!-- 版本由父POM管理，无需指定 --> </dependency> <!-- Spring Boot Starter Test --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <!-- Lombok --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>${lombok.version}</version> <scope>provided</scope> <!-- 对应Gradle的compileOnly --> </dependency> <!-- MySQL Connector --> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <!-- 版本可能由Spring Boot管理，也可在properties中自定义 --> <scope>runtime</scope> <!-- 对应Gradle的runtimeOnly --> </dependency> <!-- 其他依赖... --> <!-- 仔细核对 gradle_runtime_dependencies.txt 文件，逐一添加 --> </dependencies> <build> <plugins> <!-- Spring Boot Maven Plugin：用于打包可执行jar --> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <!-- Maven Compiler Plugin：父POM已配置，通常无需重复 --> <!-- 如果需要特殊配置，可以覆盖 --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>${java.version}</source> <target>${java.version}</target> <encoding>${project.build.sourceEncoding}</encoding> </configuration> </plugin> </plugins> <!-- 资源文件过滤配置（如果需要） --> <resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> <!-- 是否替换资源文件中的占位符 --> <includes> <include>**/*.properties</include> <include>**/*.yml</include> </includes> </resource> </resources> </build> </project>

校对关键点：

1. 依赖版本核对：这是最容易出错的地方。将生成的pom.xml中的依赖与gradle_dependencies.txt报告逐一对比。重点关注那些没有从父POM继承版本的依赖（如Lombok、某些工具类库）。确保版本号一致。Maven的依赖传递机制和Gradle不同，有时需要显式声明某个传递依赖的版本以避免冲突。
2. Scope映射核对：根据2.1节的映射关系，检查每个依赖的<scope>是否正确。特别是provided和runtime，弄错会导致编译错误或打包体积过大。
3. 插件功能替代：在Gradle中，java插件自动完成了编译、测试、打包等任务。在Maven中，这是由maven-compiler-plugin,maven-surefire-plugin,maven-jar-plugin等完成的。如果你继承了spring-boot-starter-parent，这些插件都已预配置好。否则，你需要手动添加和配置它们。
4. 仓库配置：如果Gradle项目配置了阿里云、华为云等镜像仓库，你需要在Maven的settings.xml（用户全局或项目级）或pom.xml的<repositories>中配置对应的镜像，以加速依赖下载。

4. 构建验证与常见问题排错

生成并完善pom.xml后，绝不能假设迁移已经成功。必须通过严格的构建和测试来验证。

4.1 执行Maven构建生命周期

在包含pom.xml的根目录下，打开新的终端（避免Gradle环境变量干扰），执行标准构建命令：

mvn clean compile

此命令清理旧编译结果并编译主代码。这是第一道关卡，可以检查编译时依赖（compilescope）是否齐全，语法是否兼容。

mvn clean test

此命令编译并运行所有测试。这是验证迁移是否成功的黄金标准。如果所有测试通过，说明代码的核心功能在Maven环境下运行正常。测试依赖（testscope）是否正确配置也在此环节验证。

mvn clean package

此命令执行完整构建并打包（生成target/*.jar或target/*.war）。这会验证运行时依赖（runtimescope）和打包插件（如spring-boot-maven-plugin）的配置是否正确。

4.2 典型问题与解决方案

在验证过程中，你几乎一定会遇到一些问题。以下是几个高频问题及其排查思路：

问题一：依赖找不到（Could not resolve dependencies）

• 现象：mvn compile失败，提示某个artifactId或version在仓库中不存在。
• 排查：
  1. 检查pom.xml中该依赖的groupId,artifactId,version是否拼写正确。
  2. 去 Maven中央仓库 或你配置的镜像仓库网页搜索该坐标，确认是否存在。
  3. 特别关注版本号。Gradle有时可以使用+表示动态版本，或者通过platform/BOM管理版本。Maven中需要固定具体的版本号，或者通过<dependencyManagement>导入BOM。
  4. 检查是否需要添加特定的<repository>（比如有些公司私有库或Spring Milestone仓库）。

问题二：类找不到（ClassNotFoundException或NoClassDefFoundError）

• 现象：编译成功，但运行测试或启动应用时抛类找不到异常。
• 排查：
  1. Scope错误：最可能的原因。一个在Gradle中是implementation的依赖，在Maven中被错误地声明为provided或test。回顾2.1节的映射，修正<scope>。
  2. 依赖缺失：某个必要的传递依赖在Maven的依赖树中没有被引入。使用mvn dependency:tree命令查看完整的依赖树，与Gradle的dependencies输出对比，找到缺失的依赖并显式声明。
  3. 包路径冲突：罕见的包名/类名冲突。使用mvn dependency:tree -Dverbose查看冲突，并用<exclusions>排除不需要的传递依赖。

问题三：测试失败

• 现象：mvn test失败，但之前gradle test是成功的。
• 排查：
  1. 测试依赖：确认所有测试专用的依赖（如JUnit 5的junit-jupiter-api,junit-jupiter-engine，Mockito等）都已正确添加，且scope为test。
  2. 测试资源：Gradle的src/test/resources目录默认会被加入测试类路径。Maven同样如此。但如果你的测试代码动态读取资源文件，注意路径差异。可以使用getClass().getResource("/file.txt")来获取。
  3. 系统属性或环境变量：有些测试可能依赖通过Gradletest任务设置的JVM系统属性。在Maven中，需要在maven-surefire-plugin配置中设置：

     <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <systemPropertyVariables> <your.property.key>property-value</your.property.key> </systemPropertyVariables> </configuration> </plugin>

问题四：打包结果不正确

• 现象：mvn package生成的jar/war文件无法运行，或缺少资源文件。
• 排查：
  1. 可执行Jar：对于Spring Boot项目，必须使用spring-boot-maven-plugin，否则打出来的jar没有内嵌容器和主类信息。确保该插件已配置。
  2. 资源文件遗漏：检查<build><resources>配置。默认情况下，src/main/resources下的文件会被复制到target/classes并打包。如果你的资源文件在非标准位置，需要在这里额外配置<resource>。
  3. 主类清单：非Spring Boot的普通可执行Jar，需要在maven-jar-plugin中配置<archive>和<manifest>来指定主类。

5. 多模块项目的迁移策略

单模块项目的迁移相对直接。对于多模块项目，迁移需要更系统的规划。核心思想是：先建立Maven的父子项目结构，再逐个模块迁移。

5.1 建立Maven项目结构

假设原Gradle项目结构如下：

my-multi-module-project/ ├── build.gradle ├── settings.gradle ├── module-api/ │ └── build.gradle ├── module-service/ │ └── build.gradle └── module-web/ └── build.gradle

目标Maven结构：

my-multi-module-project/ ├── pom.xml (父POM，打包类型为pom) ├── module-api/ │ ├── pom.xml │ └── src/ ├── module-service/ │ ├── pom.xml │ └── src/ └── module-web/ ├── pom.xml └── src/

1. 创建父POM：在项目根目录创建pom.xml，其<packaging>为pom，并在<modules>中列出所有子模块。

   <!-- 根目录 pom.xml --> <project ...> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>my-multi-module-parent</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>pom</packaging> <!-- 关键！ --> <modules> <module>module-api</module> <module>module-service</module> <module>module-web</module> </modules> <!-- 在父POM中定义公共依赖管理和属性 --> <dependencyManagement> <dependencies> <!-- 统一管理各子模块共用依赖的版本 --> </dependencies> </dependencyManagement> <properties> <!-- 公共属性 --> </properties> </project>

2. 迁移子模块：进入每个子模块目录（如module-api），使用gradle init --type pom为该模块生成独立的pom.xml。然后，手动编辑这个子pom.xml：
   • 添加<parent>指向根项目的坐标。
   • 移除父POM中已定义的公共依赖的<version>。
   • 将Gradle中implementation project(‘:module-api’)的依赖，转换为Maven中对兄弟模块的普通依赖声明，使用在子模块POM中定义的groupId和artifactId。

5.2 处理模块间依赖

这是多模块迁移的关键。在子模块module-service的pom.xml中，如果需要依赖module-api，应该这样声明：

<!-- module-service/pom.xml --> <project ...> <parent> <groupId>com.example</groupId> <artifactId>my-multi-module-parent</artifactId> <version>1.0.0-SNAPSHOT</version> </parent> <artifactId>module-service</artifactId> <dependencies> <dependency> <!-- 依赖兄弟模块 --> <groupId>com.example</groupId> <artifactId>module-api</artifactId> <version>${project.version}</version> <!-- 版本通常与父项目一致 --> </dependency> <!-- 其他外部依赖 --> </dependencies> </project>

重要提示：在Maven中，构建顺序由模块依赖关系自动决定。你需要先在根目录执行mvn clean install，将子模块安装到本地仓库，这样其他模块才能引用到。或者，始终在根目录执行mvn clean compile/package，Maven会按正确顺序构建所有模块。

6. 迁移后的优化与收尾工作

当所有模块都能通过mvn clean test和mvn clean package后，迁移的主要技术工作就完成了。但为了让项目更健壮、更符合Maven生态的最佳实践，还需要做一些优化和收尾。

6.1 利用Maven特性优化配置

1. 依赖管理（Dependency Management）：在父POM中使用<dependencyManagement>统一管理所有子模块共用的依赖版本。这能极大避免版本冲突，类似于Gradle的platform或版本目录（Version Catalog）。

   <dependencyManagement> <dependencies> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>${lombok.version}</version> </dependency> <!-- 其他通用依赖 --> </dependencies> </dependencyManagement>

   子模块中引用这些依赖时，可以省略<version>标签。
2. 插件管理（Plugin Management）：同样，在父POM中使用<pluginManagement>统一配置各模块共用的插件版本和配置，确保构建行为一致。
3. 资源过滤与Profile：Maven的资源过滤（<filtering>true</filtering>）功能强大，可以结合<profiles>为不同环境（dev, test, prod）打包不同的配置文件。这是Gradle需要额外插件才能方便实现的功能，现在可以原生用起来。

6.2 清理与文档更新

1. 移除Gradle文件：确认Maven构建完全稳定后，可以安全删除Gradle相关的文件了：
   • build.gradle,settings.gradle,gradle.properties
   • gradle/目录
   • gradlew,gradlew.bat
   • 项目中的.gradle缓存目录（通常可以忽略）

   谨慎操作：建议先使用Git等版本控制系统提交Maven化后的稳定代码，然后再删除这些文件。或者先将它们移动到一个备份目录。

2. 更新IDE项目文件：如果你使用IntelliJ IDEA或Eclipse，需要重新导入项目。
   • IntelliJ IDEA：关闭项目。删除项目根目录下的.idea目录和所有的.iml文件。然后使用File -> Open，选择包含pom.xml的根目录，IDEA会将其识别为Maven项目并重新导入。
   • Eclipse：删除项目（不从磁盘删除）。然后使用File -> Import -> Maven -> Existing Maven Projects重新导入。
3. 更新CI/CD流水线：将Jenkins、GitLab CI等持续集成脚本中的构建命令，从./gradlew build改为mvn clean package。同时检查是否需要更新构建节点上的工具安装（从Gradle切换到Maven）。
4. 更新项目README：在项目说明文档中，将构建指南从Gradle命令更新为Maven命令。

6.3 最后的验证清单

在宣布迁移完成前，运行一遍这个清单：

• [ ]mvn clean compile成功。
• [ ]mvn clean test成功（所有单元测试和集成测试通过）。
• [ ]mvn clean package成功，生成的jar/war包在目标环境（如测试服务器）可正常启动运行。
• [ ] 多模块项目在根目录执行mvn clean install，所有模块按顺序构建成功，且模块间依赖正确。
• [ ] IDE中项目导入正常，代码无报错，依赖库显示正确，运行/调试配置可正常工作。
• [ ] 团队其他成员能用新的Maven配置成功拉取代码并构建。

迁移本身是一次性的，但理解两个工具背后的设计理念，能让你在未来无论使用哪种工具都更加得心应手。Gradle的灵活和性能与Maven的约定和稳定，各有其适用场景。这次转换过程，实际上是一次对项目构建生命周期的深度梳理，往往能发现并清理掉一些陈旧的、不必要的依赖或配置，让项目结构变得更加清晰。