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/ // 可能存在的根项目源码不常见于多模块你需要仔细阅读以下几个关键文件settings.gradle这是你的“地图”。它会用include语句明确列出所有子模块例如include ‘:submodule-a’, ‘:submodule-b’。这直接决定了你转换后Maven项目里会有多少个module。根目录build.gradle这里通常配置了所有子模块共用的东西。比如allprojects或subprojects块里面定义的仓库repositories、插件plugins、依赖dependencies通常是全局生效的。buildscript块这里定义的依赖是为构建脚本本身服务的比如一些特殊的Gradle插件这部分在转换到Maven时通常不需要处理除非插件有对应的Maven插件。项目属性如group对应Maven的groupId、version对应version。artifactId在Gradle里通常隐含在目录名中转换时需要显式定义。各子模块的build.gradle这里定义了模块独有的依赖、插件和任务。要逐行分析特别是dependencies里的implementation、api、compileOnly、runtimeOnly等配置它们对应Maven依赖的不同scope。注意Gradle的依赖配置如implementation和Maven的依赖作用域scope不是严格一一对应的。这是转换中最容易出错的地方之一后面会详细讲。2.2 工具与环境准备清单工欲善其事必先利其器。转换过程我们会用到几个工具提前装好。Maven环境确保你的开发机上安装了Maven并且mvn命令可以在终端中运行。用mvn -v检查一下。IDE准备IntelliJ IDEA或Eclipse都行。IDE对两种构建工具都有很好的支持能在转换过程中帮你验证pom.xml的语法和依赖解析。我个人更推荐IDEA它在处理两种构建工具混合项目时更智能一些。一个干净的目录强烈建议不要直接在原Gradle项目上修改。将项目复制一份到新目录在新目录中进行转换操作。这样万一转换失败你还有完整的原项目可以回滚这是最重要的安全底线。2.3 制定转换策略与核对清单在开始“翻译”之前先想好整体策略。对于多模块项目我建议采用“自底向上”的策略先处理叶子模块即那些不包含其他子模块的、最底层的模块。先为它们生成pom.xml因为它们的依赖关系最简单。再处理聚合模块即根目录项目它的pom.xml中需要通过modules列出所有子模块并打包方式packaging设为pom。最后处理依赖传递在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 version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion !-- 坐标这是项目的唯一标识 -- groupIdcom.yourcompany/groupId artifactIdyour-artifact-id/artifactId version1.0.0-SNAPSHOT/version packagingjar/packaging !-- 也可能是 war, pom 等 -- properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding maven.compiler.source11/maven.compiler.source !-- 根据你的Java版本修改 -- maven.compiler.target11/maven.compiler.target /properties !-- 更多配置将在这里添加 -- /project现在我们来填充关键信息groupId通常对应Gradle根build.gradle里的group属性。例如Gradle中group com.example这里就填groupIdcom.example/groupId。artifactIdGradle中没有直接对应项。最佳实践是使用模块的目录名或者参考Gradle中可能设置的archivesBaseName属性。例如模块目录叫user-serviceartifactId就设为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 - scopecompile (默认可省略) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version2.7.0/version /dependency !-- compileOnly - scopeprovided -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.24/version scopeprovided/scope /dependency !-- runtimeOnly - scoperuntime -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.30/version scoperuntime/scope /dependency !-- testImplementation - scopetest -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId version2.7.0/version scopetest/scope /dependency !-- api - scopecompile (对于Mavenapi和implementation在消费方看来都是compile) -- dependency groupIdcom.google.guava/groupId artifactIdguava/artifactId version31.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 groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.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 idcentral/id urlhttps://repo.maven.apache.org/maven2/url /repository repository idaliyun/id urlhttps://maven.aliyun.com/repository/public/url /repository /repositories !-- 插件仓库通常也需要类似配置 -- pluginRepositories repository idcentral/id urlhttps://repo.maven.apache.org/maven2/url /repository /pluginRepositories实操心得国内网络环境强烈建议在Maven的全局配置文件~/.m2/settings.xml中配置阿里云等镜像而不是在每个项目的pom.xml里配。这样一劳永逸所有项目都能加速。3.4 多模块项目结构的构建对于多模块项目根目录的pom.xml角色至关重要它不再是一个可打包的模块而是一个“聚合器”。根pom.xml配置packaging必须设为pom。通过modules标签列出所有子模块路径是相对于根pom.xml的目录名。通常在这里定义所有子模块共享的配置如properties、dependencyManagement、build中的通用插件配置等。!-- 根目录 pom.xml -- groupIdcom.yourcompany/groupId artifactIdparent-project/artifactId version1.0.0-SNAPSHOT/version packagingpom/packaging modules modulesubmodule-a/module modulesubmodule-b/module /modules properties java.version11/java.version spring-boot.version2.7.0/spring-boot.version /properties dependencyManagement dependencies !-- 在这里统一管理依赖版本 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version${spring-boot.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement子模块pom.xml配置子模块必须通过parent标签指向根模块。子模块的groupId和version通常继承自父POM可以省略只需定义自己的artifactId。子模块之间的依赖直接像依赖外部库一样声明即可Maven会根据模块关系自动处理。!-- submodule-a/pom.xml -- parent groupIdcom.yourcompany/groupId artifactIdparent-project/artifactId version1.0.0-SNAPSHOT/version /parent artifactIdsubmodule-a/artifactId dependencies !-- 依赖另一个子模块 -- dependency groupIdcom.yourcompany/groupId artifactIdsubmodule-b/artifactId version${project.version}/version !-- 使用当前项目版本 -- /dependency /dependencies4. 验证、测试与问题排查转换完成后千万别以为大功告成。验证环节和转换本身一样重要。4.1 基础构建验证进入项目根目录执行Maven最基本的命令来验证项目结构是否正确mvn clean compile这个命令会清理旧构建、编译所有模块。观察输出如果成功你会看到BUILD SUCCESS。如果失败控制台会打印详细的错误信息。最常见的错误是依赖找不到检查依赖的groupId、artifactId、version是否拼写正确特别是artifactId是否和依赖模块定义的完全一致大小写敏感。检查仓库配置是否正确网络是否通畅。pom.xml语法错误比如标签未闭合、属性引用错误${xxx}。IDE通常能帮你提前发现。4.2 功能与集成测试验证编译通过只是第一步要确保项目行为没有变化。运行单元测试执行mvn clean test。确保所有在Gradle下能通过的测试在Maven下同样通过。重点关注测试中是否因为类路径Classpath的差异比如implementation和api的转换导致某些类在测试时不可见。打包验证执行mvn clean package。检查生成的Jar/War包包内容是否完整比如配置文件、第三方依赖是否被打进去。对于Spring Boot项目检查是否生成了可执行的“fat jar”。对比Gradle和Maven打包出来的产物可以用jar tf your.jar命令列出内容进行粗略比较。运行应用如果是个可运行的应用用Maven打包后启动它例如Spring Boot的java -jar进行基本的冒烟测试确保核心功能正常。4.3 常见问题与解决方案速查表转换过程中你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格方便你快速排查。问题现象可能原因解决方案编译错误找不到符号无法解析类1. 依赖的scope不正确如provided依赖在运行时缺失。2. 子模块间依赖的artifactId或version写错。3. 依赖本身在仓库中不存在拼写错误或版本号错误。1. 检查依赖的scope根据依赖的实际用途调整编译需要就用compile运行时环境提供就用provided。2. 仔细核对子模块依赖中的三要素确保与依赖模块pom.xml中的定义完全一致。3. 去Maven中央仓库或你配置的镜像仓库网站搜索确认依赖坐标。测试通过但运行时出现NoClassDefFoundError或ClassNotFoundException1. 依赖作用域为test的jar包被错误地用于运行时。2. 多模块项目中某个模块的依赖没有正确传递。3. 打包时依赖未包含进去例如scopeprovided/scope的依赖在独立运行时缺失。1. 检查报错类所在的依赖将其scope从test改为compile或runtime。2. 在Maven中依赖默认会传递。如果A依赖BB依赖C那么A会自动拥有C除非B对C的依赖是test或provided。检查依赖链。3. 对于需要打包进去的依赖确保其scope不是provided。对于Spring Boot使用对应的starter或配置maven-shade-plugin。mvn compile成功但IDE如IDEA依然报红IDE的Maven项目模型没有正确导入或更新。1. 在IDEA中右键点击项目根目录的pom.xml选择Maven - Reload Project。2. 检查IDEA中Maven的配置Settings - Build - Build Tools - Maven确认使用的是你本地安装的Maven并且settings.xml和仓库路径正确。3. 尝试关闭项目删除项目目录下的.idea文件夹和所有*.iml文件然后重新用IDEA打开根目录的pom.xml。构建速度异常缓慢1. Maven正在从远程仓库下载大量依赖或插件。2. 没有配置国内镜像仓库。1. 首次构建会下载所有依赖到本地仓库~/.m2/repository这是正常的。后续构建会快很多。2.务必配置国内镜像。在~/.m2/settings.xml中配置阿里云镜像可以极大加速下载。资源文件如.properties,.xml未被打包或内容不对Maven默认的资源过滤规则与Gradle不同。Gradle中可能在sourceSets里定制了资源目录或过滤规则。在Maven的pom.xml中配置buildresources部分明确指定资源目录和过滤规则。例如xml resources resource directorysrc/main/resources/directory filteringtrue/filtering !-- 是否替换占位符 -- /resource /resources自定义的Gradle任务task找不到对应Maven插件实现一些高度定制化的Gradle任务在Maven生态中没有直接对应的插件。1. 寻找功能相近的Maven插件如maven-antrun-plugin可以执行Ant任务exec-maven-plugin可以执行系统命令。2. 如果任务逻辑简单考虑将其编写成一个独立的Java/Groovy脚本在Maven构建生命周期中通过exec-maven-plugin调用。3. 评估该自定义任务是否真的必要或许有更标准的Maven方式可以实现。4.4 转换后的收尾工作验证全部通过后还有一些收尾工作让项目更干净清理Gradle残留文件删除项目中的build.gradle、settings.gradle、gradlew、gradlew.bat、gradle/目录以及各模块下的build/目录构建输出。更新版本控制忽略文件如果你的项目使用Git更新.gitignore文件移除Gradle相关的忽略项如.gradle/,build/并确保添加了Maven的忽略项如target/。更新文档更新项目的README、构建说明等文档将Gradle命令./gradlew build替换为Maven命令mvn clean package。通知团队告知团队成员项目构建工具已切换并提供新的构建和开发指引。整个转换过程从分析到验证完成对于一个中等复杂度的多模块项目大概需要4-8小时。核心在于细心尤其是依赖和作用域的映射。手动转换虽然繁琐但能让你对项目的构建逻辑有更深的理解以后无论用哪种工具都能得心应手。如果你遇到上面表格里没覆盖的怪问题最好的方法是去对比Gradle构建时详细的输出日志用./gradlew build --info和Maven构建的日志往往能发现蛛丝马迹。