Gradle项目迁移Maven实战：依赖映射、多模块构建与验证指南

1. 项目概述：为什么要把Gradle项目转成Maven？

最近在整理一个老项目，发现它用的是Gradle构建。团队里新来的小伙伴对Gradle不太熟，维护起来有点吃力，而且我们内部CI/CD流水线对Maven的支持更成熟。所以，我决定把这个项目从Gradle迁移到Maven。这听起来像是个大工程，但其实只要理清思路，一步步来，半天时间就能搞定。这篇文章，我就把整个转换过程，从思路分析到每个文件的具体改动，结合踩过的坑和注意事项，给你完整地捋一遍。无论你是团队技术栈统一，还是单纯想学习两种构建工具的转换逻辑，这篇实操指南都能让你直接“抄作业”。

Gradle和Maven都是Java生态里顶流的构建工具。Gradle灵活，用Groovy或Kotlin DSL写脚本，功能强大；Maven约定大于配置，用XML写pom.xml，结构规范，生态插件丰富。转换的核心，就是把Gradle构建脚本（主要是build.gradle或build.gradle.kts）里定义的依赖、插件、仓库、构建生命周期等配置，“翻译”成Maven能懂的pom.xml。这不仅仅是格式转换，更是构建理念的迁移。

2. 转换前的核心准备工作

动手之前，做好准备工作能避免很多回头路。别急着直接改文件，先把项目情况和转换目标搞清楚。

2.1 深度解析现有Gradle项目结构

首先，打开你的Gradle项目，别只看根目录的build.gradle。一个典型的、结构稍微复杂点的项目可能是这样的：

your-gradle-project/ ├── build.gradle (或 build.gradle.kts) // 根项目构建脚本 ├── settings.gradle (或 settings.gradle.kts) // 项目设置，包含子模块定义 ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties // 指定Gradle版本 ├── gradlew (Unix脚本) ├── gradlew.bat (Windows脚本) ├── submodule-a/ // 子模块A │ ├── build.gradle │ └── src/ ├── submodule-b/ // 子模块B │ ├── build.gradle │ └── src/ └── src/ // 可能存在的根项目源码（不常见于多模块）

你需要仔细阅读以下几个关键文件：

1. settings.gradle：这是你的“地图”。它会用include语句明确列出所有子模块（例如include ‘:submodule-a’, ‘:submodule-b’）。这直接决定了你转换后Maven项目里会有多少个<module>。
2. 根目录build.gradle：这里通常配置了所有子模块共用的东西。比如：
   • allprojects或subprojects块：里面定义的仓库（repositories）、插件（plugins）、依赖（dependencies）通常是全局生效的。
   • buildscript块：这里定义的依赖是为构建脚本本身服务的（比如一些特殊的Gradle插件），这部分在转换到Maven时通常不需要处理，除非插件有对应的Maven插件。
   • 项目属性：如group（对应Maven的groupId）、version（对应version）。artifactId在Gradle里通常隐含在目录名中，转换时需要显式定义。
3. 各子模块的build.gradle：这里定义了模块独有的依赖、插件和任务。要逐行分析，特别是dependencies里的implementation、api、compileOnly、runtimeOnly等配置，它们对应Maven依赖的不同scope。

注意：Gradle的依赖配置（如implementation）和Maven的依赖作用域（scope）不是严格一一对应的。这是转换中最容易出错的地方之一，后面会详细讲。

2.2 工具与环境准备清单

工欲善其事，必先利其器。转换过程我们会用到几个工具，提前装好。

1. Maven环境：确保你的开发机上安装了Maven，并且mvn命令可以在终端中运行。用mvn -v检查一下。
2. IDE准备：IntelliJ IDEA或Eclipse都行。IDE对两种构建工具都有很好的支持，能在转换过程中帮你验证pom.xml的语法和依赖解析。我个人更推荐IDEA，它在处理两种构建工具混合项目时更智能一些。
3. 一个干净的目录：强烈建议不要直接在原Gradle项目上修改。将项目复制一份到新目录，在新目录中进行转换操作。这样万一转换失败，你还有完整的原项目可以回滚，这是最重要的安全底线。

2.3 制定转换策略与核对清单

在开始“翻译”之前，先想好整体策略。对于多模块项目，我建议采用“自底向上”的策略：

1. 先处理叶子模块：即那些不包含其他子模块的、最底层的模块。先为它们生成pom.xml，因为它们的依赖关系最简单。
2. 再处理聚合模块：即根目录项目，它的pom.xml中需要通过<modules>列出所有子模块，并打包方式（packaging）设为pom。
3. 最后处理依赖传递：在Maven中，子模块之间的依赖使用<dependency>声明，并且要特别注意groupId、artifactId、version三要素必须与依赖模块的pom.xml中定义的一致。

我列了一个转换核对清单，你可以边操作边打勾：

• [ ] 分析清楚项目模块结构（根据settings.gradle）。
• [ ] 确定每个模块的Maven坐标（groupId,artifactId,version）。
• [ ] 梳理清楚每个模块的依赖项（Gradle -> Maven Scope映射）。
• [ ] 梳理并找到Gradle插件对应的Maven插件（如果有）。
• [ ] 处理项目资源文件（如src/main/resources）的过滤和包含规则。
• [ ] 处理构建产物（Jar包）的命名、内容等定制化配置。

3. 核心转换实操：从build.gradle到pom.xml

这是最核心的一步，我们手动“翻译”构建逻辑。虽然有一些自动化工具（如gradle2maven插件），但它们往往无法处理复杂的定制逻辑，手动转换虽然慢，但最可靠、最可控。

3.1 Maven项目骨架与坐标定义

首先，在每个模块的目录下（包括根目录），创建一个pom.xml文件。一个最基础的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> <!-- 坐标：这是项目的唯一标识 --> <groupId>com.yourcompany</groupId> <artifactId>your-artifact-id</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>jar</packaging> <!-- 也可能是 war, pom 等 --> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.source>11</maven.compiler.source> <!-- 根据你的Java版本修改 --> <maven.compiler.target>11</maven.compiler.target> </properties> <!-- 更多配置将在这里添加 --> </project>

现在，我们来填充关键信息：

• groupId：通常对应Gradle根build.gradle里的group属性。例如Gradle中group = 'com.example'，这里就填<groupId>com.example</groupId>。
• artifactId：Gradle中没有直接对应项。最佳实践是使用模块的目录名，或者参考Gradle中可能设置的archivesBaseName属性。例如模块目录叫user-service，artifactId就设为user-service。保持简洁、有意义且唯一。
• version：对应Gradle中的version属性。例如version = '0.1.0'。
• packaging：默认是jar。如果你的模块是Web应用，打包成WAR，则改为war。对于仅仅为了聚合子模块的根目录pom.xml，必须设为pom。

3.2 依赖项（Dependencies）的精确迁移

这是工作量最大也最容易出错的部分。Gradle的依赖配置更精细，需要准确映射到Maven的scope。

打开子模块的build.gradle，找到dependencies块。我们来看一个例子并转换：

dependencies { implementation 'org.springframework.boot:spring-boot-starter-web:2.7.0' compileOnly 'org.projectlombok:lombok:1.18.24' runtimeOnly 'mysql:mysql-connector-java:8.0.30' testImplementation 'org.springframework.boot:spring-boot-starter-test:2.7.0' api 'com.google.guava:guava:31.1-jre' }

转换到Maven的pom.xml中，<dependencies>部分应该像这样：

<dependencies> <!-- implementation -> scope=compile (默认，可省略) --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.7.0</version> </dependency> <!-- compileOnly -> scope=provided --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.24</version> <scope>provided</scope> </dependency> <!-- runtimeOnly -> scope=runtime --> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.30</version> <scope>runtime</scope> </dependency> <!-- testImplementation -> scope=test --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <version>2.7.0</version> <scope>test</scope> </dependency> <!-- api -> scope=compile (对于Maven，api和implementation在消费方看来都是compile) --> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>31.1-jre</version> </dependency> </dependencies>

关键映射关系与避坑指南：

• implementation/api：在Gradle中，api会暴露依赖给下游模块，而implementation不会。但在Maven中，没有这个区分。通常，两者都映射为默认的compilescope（即不写<scope>）。这可能导致转换后Maven项目的依赖传递比原Gradle项目更“宽泛”，在极少数情况下会引起类路径冲突，需要留意。
• compileOnly：对应Maven的provided。表示依赖仅在编译和测试时需要，运行时由容器或JDK提供。
• runtimeOnly：对应Maven的runtime。表示依赖仅在运行时需要，编译时不需要。
• testImplementation：对应Maven的test。
• annotationProcessor：这是Gradle用于注解处理的配置。在Maven中，通常由对应的插件（如maven-compiler-plugin）配置注解处理器路径，或者某些注解处理器依赖（如Lombok）即使声明为compile也能工作。对于Lombok，在Maven中通常只需providedscope依赖，并在maven-compiler-plugin中配置（现代版本IDEA通常能自动识别）。
• 依赖版本管理：如果Gradle项目使用了ext或version catalogs统一管理版本，你需要把版本号提取到Maven的<properties>标签中，或者在父POM的<dependencyManagement>里统一定义，这是保持整洁的好习惯。

3.3 构建插件（Plugins）与仓库（Repositories）迁移

插件迁移：Gradle插件功能强大，Maven靠插件实现类似功能。你需要为每个Gradle插件找到对应的Maven插件。

• Java插件：Gradle的apply plugin: 'java'或plugins { id 'java' }，对应Maven默认的构建生命周期，无需额外配置。
• Spring Boot插件：id 'org.springframework.boot' version '2.7.0'。在Maven中，通常通过继承特定的parentPOM来实现：

  <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.0</version> </parent>

  或者使用spring-boot-maven-plugin插件。
• 发布插件：如maven-publish。在Maven中，使用maven-deploy-plugin配合distributionManagement配置来实现发布。
• 自定义任务：Gradle中你可能写了一些自定义的task（比如复制文件、生成代码）。在Maven中，你需要找到能实现相同功能的插件（如maven-antrun-plugin、exec-maven-plugin），或者用maven-resources-plugin配合资源过滤来处理。

仓库迁移：Gradle中在repositories块里配置的仓库，需要搬到Maven的<repositories>和<pluginRepositories>中。

// Gradle repositories { mavenCentral() maven { url 'https://maven.aliyun.com/repository/public' } // 阿里云镜像 }

<!-- Maven pom.xml --> <repositories> <repository> <id>central</id> <url>https://repo.maven.apache.org/maven2</url> </repository> <repository> <id>aliyun</id> <url>https://maven.aliyun.com/repository/public</url> </repository> </repositories> <!-- 插件仓库通常也需要类似配置 --> <pluginRepositories> <repository> <id>central</id> <url>https://repo.maven.apache.org/maven2</url> </repository> </pluginRepositories>

实操心得：国内网络环境，强烈建议在Maven的全局配置文件（~/.m2/settings.xml）中配置阿里云等镜像，而不是在每个项目的pom.xml里配。这样一劳永逸，所有项目都能加速。

3.4 多模块项目结构的构建

对于多模块项目，根目录的pom.xml角色至关重要，它不再是一个可打包的模块，而是一个“聚合器”。

1. 根pom.xml配置：

   • packaging必须设为pom。
   • 通过<modules>标签列出所有子模块，路径是相对于根pom.xml的目录名。
   • 通常在这里定义所有子模块共享的配置，如<properties>、<dependencyManagement>、<build>中的通用插件配置等。

   <!-- 根目录 pom.xml --> <groupId>com.yourcompany</groupId> <artifactId>parent-project</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>pom</packaging> <modules> <module>submodule-a</module> <module>submodule-b</module> </modules> <properties> <java.version>11</java.version> <spring-boot.version>2.7.0</spring-boot.version> </properties> <dependencyManagement> <dependencies> <!-- 在这里统一管理依赖版本 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>${spring-boot.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

2. 子模块pom.xml配置：

   • 子模块必须通过<parent>标签指向根模块。
   • 子模块的groupId和version通常继承自父POM，可以省略，只需定义自己的artifactId。
   • 子模块之间的依赖，直接像依赖外部库一样声明即可，Maven会根据模块关系自动处理。

   <!-- submodule-a/pom.xml --> <parent> <groupId>com.yourcompany</groupId> <artifactId>parent-project</artifactId> <version>1.0.0-SNAPSHOT</version> </parent> <artifactId>submodule-a</artifactId> <dependencies> <!-- 依赖另一个子模块 --> <dependency> <groupId>com.yourcompany</groupId> <artifactId>submodule-b</artifactId> <version>${project.version}</version> <!-- 使用当前项目版本 --> </dependency> </dependencies>

4. 验证、测试与问题排查

转换完成后，千万别以为大功告成。验证环节和转换本身一样重要。

4.1 基础构建验证

进入项目根目录，执行Maven最基本的命令来验证项目结构是否正确：

mvn clean compile

这个命令会清理旧构建、编译所有模块。观察输出：

• 如果成功，你会看到BUILD SUCCESS。
• 如果失败，控制台会打印详细的错误信息。最常见的错误是：
  • 依赖找不到：检查依赖的groupId、artifactId、version是否拼写正确，特别是artifactId是否和依赖模块定义的完全一致（大小写敏感）。检查仓库配置是否正确，网络是否通畅。
  • pom.xml语法错误：比如标签未闭合、属性引用错误（${xxx}）。IDE通常能帮你提前发现。

4.2 功能与集成测试验证

编译通过只是第一步，要确保项目行为没有变化。

1. 运行单元测试：执行mvn clean test。确保所有在Gradle下能通过的测试，在Maven下同样通过。重点关注测试中是否因为类路径（Classpath）的差异（比如implementation和api的转换）导致某些类在测试时不可见。
2. 打包验证：执行mvn clean package。检查生成的Jar/War包：
   • 包内容是否完整（比如配置文件、第三方依赖是否被打进去）。
   • 对于Spring Boot项目，检查是否生成了可执行的“fat jar”。
   • 对比Gradle和Maven打包出来的产物，可以用jar tf your.jar命令列出内容进行粗略比较。
3. 运行应用：如果是个可运行的应用，用Maven打包后启动它（例如Spring Boot的java -jar），进行基本的冒烟测试，确保核心功能正常。

4.3 常见问题与解决方案速查表

转换过程中，你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格，方便你快速排查。

4.4 转换后的收尾工作

验证全部通过后，还有一些收尾工作让项目更干净：

1. 清理Gradle残留文件：删除项目中的build.gradle、settings.gradle、gradlew、gradlew.bat、gradle/目录以及各模块下的build/目录（构建输出）。
2. 更新版本控制忽略文件：如果你的项目使用Git，更新.gitignore文件，移除Gradle相关的忽略项（如.gradle/,build/），并确保添加了Maven的忽略项（如target/）。
3. 更新文档：更新项目的README、构建说明等文档，将Gradle命令（./gradlew build）替换为Maven命令（mvn clean package）。
4. 通知团队：告知团队成员项目构建工具已切换，并提供新的构建和开发指引。

整个转换过程，从分析到验证完成，对于一个中等复杂度的多模块项目，大概需要4-8小时。核心在于细心，尤其是依赖和作用域的映射。手动转换虽然繁琐，但能让你对项目的构建逻辑有更深的理解，以后无论用哪种工具都能得心应手。如果你遇到上面表格里没覆盖的怪问题，最好的方法是去对比Gradle构建时详细的输出日志（用./gradlew build --info）和Maven构建的日志，往往能发现蛛丝马迹。