尧图网页设计 
Maven 这个工具但凡写过 Java 的人多少都接触过但说实话很多人在 IDEA 里一键点“刷新”之后就再也没深究过它到底在干什么。直到有一天新电脑装环境、CI 上构建失败、依赖拉不下来才意识到自己连 Maven 的安装目录在哪都说不清楚。这篇内容我就从零开始把 Maven 的安装、配置、仓库管理、常用命令、多模块部署这些环节全部过一遍包含我这些年实际踩过的坑和一直在用的配置方案希望能帮你把 Maven 这块彻底理顺。这篇内容适合谁刚接触 Java 生态、想把本地开发环境彻底搞清楚的新人也包括已经写了几个月代码、但一直靠 IDE 自动搞定依赖、想弄明白底层原理的同学。读完你至少能自己搞定 Maven 安装、配置阿里云镜像、命令行打包、多模块项目构建这些事遇到“依赖下载失败”“仓库爆红”这类问题也不会再慌。1. 内容整体设计与思路拆解1.1 Maven 到底是什么它解决了什么问题先别急着下载安装我们得先弄清楚 Maven 在 Java 生态里扮演的角色。你可以把它理解成一个“项目管家”负责三件事依赖管理、项目构建、项目信息管理。依赖管理是大多数人最先接触到的功能。以前写 Java 项目要把 jar 包手动下载下来扔进lib目录再在 IDE 里逐个添加为库。换台电脑就得重新折腾一遍团队协作时“我这边能跑你那边报错”是家常便饭。Maven 用pom.xml文件统一声明依赖坐标groupId、artifactId、version构建时自动从仓库下载对应 jar 包彻底告别手动拷贝。项目构建则是把编译、测试、打包、安装这些原本需要一串命令串联起来的步骤变成mvn clean install一句话的事。Maven 定义了标准的生命周期从 validate 到 deploy 一整套流程每个阶段绑定特定插件你只需要知道自己在哪个节点执行哪个命令就行。这两点加起来Maven 就变成了 Java 项目的事实标准。后面出现的 Gradle 虽然性能更好、写法更灵活但 Maven 的约定优于配置理念至今仍深深影响着整个 Java 构建生态。所以哪怕你现在用的是 Gradle理解 Maven 的核心理念也全是收益。1.2 为什么我要写“从零开始的实战部署”而不是单纯讲命令网上关于 Maven 的教程一搜一大把但绝大多数都停留在“怎么安装、常用命令是什么”这个层面。真正到了项目部署环节一堆实际问题就会冒出来mvn package打出来的 jar 为什么跑不起来配置文件里的仓库地址为什么不是阿里云IDEA 里明明配了 Maven 却还是用的自带版本多个项目依赖同一个 SNAPSHOT 版本为什么总是拿不到最新代码这些问题的根源其实是对 Maven 运行机制缺乏整体认知。所以这篇内容的思路是先搭好环境再讲清原理然后通过真实项目把整个构建、部署链路走一遍。你跟着操作完不仅会敲命令还能理解每条命令背后发生了什么。2. 环境准备与安装配置2.1 JDK 版本选择与安装Maven 本身是用 Java 写的运行它必须得有 JDK。先确认你本机的 Java 环境java -version这里有个容易踩的坑Maven 3.9.x 要求 JDK 8 及以上Maven 4.0 则需要 JDK 17 以上。如果你本地装的是 JDK 8就老老实实用 Maven 3.8.x 或 3.9.x别追求最新版。我见过有人在 JDK 8 的环境里强行用 Maven 4结果一堆插件不兼容构建直接崩掉。JDK 本身推荐安装 TemurinAdoptium 项目或 Amazon Corretto这两个都是 LTS 版本免费且社区活跃。别装 Oracle JDK 也行但没必要——企业里现在基本都用 OpenJDK 系。安装完成后设置好JAVA_HOME环境变量Windows 用户在系统变量的 Path 里加上%JAVA_HOME%\binmacOS/Linux 用户一般写入~/.zshrc或~/.bashrcexport JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64 export PATH$JAVA_HOME/bin:$PATH设置完记得source一下让配置生效然后重新执行java -version确认。2.2 Maven 下载安装全流程Maven 官网下载地址是maven.apache.org直接找 Latest Release 版本。建议下载apache-maven-3.9.x-bin.tar.gzLinux/macOS或apache-maven-3.9.x-bin.zipWindows不用下源码包。Windows 安装步骤解压 zip 包到指定目录比如D:\DevTools\apache-maven-3.9.9。目录路径千万别带中文和空格否则后面一堆奇怪的问题。新建环境变量MAVEN_HOME值为 Maven 解压路径。在 Path 变量中追加%MAVEN_HOME%\bin。打开新命令行窗口执行mvn -v验证。macOS 上如果你安装了 Homebrew一行命令搞定brew install maven但这里我要提醒一句通过 Homebrew 安装的 Maven 版本可能不是你想用的版本。比如你项目要求 Maven 3.8.x而 brew 默认装的是 3.9.x或更高这时候就需要手动指定版本安装或改用压缩包方式。我个人在 macOS 上还是习惯用压缩包解压到~/dev/apache-maven-3.9.9然后软链到一个固定路径这样切换版本特别方便。Linux 服务器上安装更简单一般用 wget 下载解压wget https://archive.apache.org/dist/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt ln -s /opt/apache-maven-3.9.9 /opt/maven然后把/opt/maven/bin加到 PATH 里。2.3 验证安装与检查配置是否生效安装完成后执行mvn -v输出应该类似Apache Maven 3.9.9 (8e9479a3f1f095c56d2e8f5e2f5e0c0f0e0c0f0) Maven home: /opt/maven Java version: 17.0.11, vendor: Eclipse Adoptium Runtime: /usr/lib/jvm/java-17-openjdk-amd64注意看 Maven home 和 Java version 这两行。如果 Java version 显示的不是你期望的版本说明JAVA_HOME环境变量没配对或者 IDE 里单独指定了 JDK 版本。这个问题在 IDEA 里特别常见后面我会专门讲。3. 核心配置文件与仓库机制详解3.1 settings.xml全局配置与用户配置Maven 有两份settings.xml一份在 Maven 安装目录的conf/下叫全局配置另一份在~/.m2/目录下叫用户配置。两者的优先级是用户配置覆盖全局配置。实际使用中建议改用户配置那份不要动全局配置不然升级 Maven 版本时改动会被覆盖。settings.xml里我几乎每次都要动几个地方localRepository本地仓库路径、mirror镜像配置、profile激活特定仓库或属性。下面这份是我在服务器上的常用配置骨架settings localRepository/opt/maven-repo/localRepository mirrors mirror idaliyun-central/id mirrorOfcentral/mirrorOf name阿里云中央仓库镜像/name urlhttps://maven.aliyun.com/repository/central/url /mirror /mirrors profiles profile idaliyun/id repositories repository idaliyun-public/id urlhttps://maven.aliyun.com/repository/public/url releasesenabledtrue/enabled/releases snapshotsenabledtrue/enabled/snapshots /repository /repositories /profile /profiles activeProfiles activeProfilealiyun/activeProfile /activeProfiles /settings这段配置里的mirror会把所有对中央仓库的请求转发到阿里云镜像profile则补充了阿里云的 public 仓库里面聚合了中央仓库和常用的第三方仓库对国内网络环境特别友好。3.2 本地仓库、中央仓库与镜像的关系很多新手分不清这三个概念。我打个比方本地仓库是你自己电脑上的“零食柜”中央仓库是网上的“大超市”镜像就是超市在你小区门口设的“自提点”。当你执行mvn dependency:resolve时Maven 会先看本地仓库有没有这个依赖有就直接用没有就去配置的远程仓库下载。默认的远程仓库是中央仓库repo.maven.apache.org但国内直连它经常超时或龟速。这时候配一个阿里云镜像就相当于小区门口的“自提点”下载速度快得多。还有一个关键细节本地仓库路径不需要手动建Maven 首次执行时会自动创建。但如果你改了localRepository指向一个不存在的路径Maven 也会自动建。唯一要注意的是磁盘空间——我见过于依赖本地仓库里积累了十几个G的旧包建议定期清理~/.m2/repository下那些长时间没用的 SNAPSHOT 版本。3.3 本地仓库与依赖下载的完整流程看一个真实的依赖下载过程。新建一个空项目pom.xml里只声明一个依赖dependency groupIdcom.google.guava/groupId artifactIdguava/artifactId version33.0.0-jre/version /dependency然后执行mvn dependency:resolve你会看到控制台输出了下载日志下载完成后在本地仓库的对应路径下会出现guava-33.0.0-jre.jar和同名.pom文件。Maven 下载依赖不仅仅是 jar 包还有它对应的 POM 文件因为 POM 文件里声明了这个依赖自身的传递性依赖。所以 Guava 的 jar 下载完后它依赖的failureaccess、listenablefuture这些包也会被跟着拉下来。这就是 Maven 依赖传递机制的体现。你不需要显式声明每个依赖的依赖Maven 会根据 POM 文件自动推导。但传递依赖也会引入一个问题版本冲突。当两个依赖传递到同一个库的不同版本时Maven 采用“最短路径优先”原则如果路径深度相同则先声明者优先。这个规则经常导致“我明明引了高版本为什么进来的是低版本”的困惑。3.4 阿里云镜像配置与多镜像仓库的取舍现在几乎所有国内 Java 团队都在用阿里云镜像。配置很简单在settings.xml的mirrors节点里加一段即可mirror idaliyun/id mirrorOf*/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror这里mirrorOf的值有讲究。*表示所有仓库请求都走这个镜像包括你自己在项目里配置的私有仓库。如果你公司内部有私服比如 Nexus千万别用*要写成central或者用external:*排除本地仓库。我见过有人图省事配了*结果私服的包怎么也拉不下来排查半天才发现是镜像把私服请求也劫持了。多镜像仓库场景下mirrorOf还支持逗号分隔多个仓库 ID比如mirrorOfcentral,my-repo/mirrorOf但实际项目中更推荐的做法是用 Nexus 作为私服私服上面配置代理仓库把阿里云镜像和中央仓库都代理一遍。这样团队内部所有依赖都从私服走既快又可控还能统一管理第三方上传的包。这个方案我会在后面的部署实战里具体展开。4. 命令行实操与生命周期详解4.1 从零搭建一个标准 Maven 项目跑命令之前得有项目。最正统的方式是用 Maven 原型生成mvn archetype:generate -DgroupIdcom.example -DartifactIddemo-project -DarchetypeArtifactIdmaven-archetype-quickstart -DinteractiveModefalse这条命令会生成一个标准目录结构demo-project ├── pom.xml └── src ├── main │ └── java/com/example/App.java └── test └── java/com/example/AppTest.java现在实际项目更常用的做法是去 start.spring.io 初始化一个 Spring Boot 项目或者直接用 IDEA 的 Spring Initializr。但我还是建议新手手工建一次目录能帮你真正理解 Maven 的约定src/main/java是主代码src/test/java是测试代码target是构建输出目录。这些目录都是在 POM 里配置的但 Maven 默认就这么规定除非有特殊需求否则大家都遵守这个约定。4.2 核心命令逐个拆解clean、compile、test、package、install、deploymvn clean删除 target 目录。为什么不直接 build 而要先 clean因为 Maven 默认不会自动清理旧的 class 文件和资源增量构建可能把上一次编译残留的 class 带进来导致“改了代码但跑起来还是旧的”这种灵异问题。所以 CI 里一般都会先 clean 再 build。mvn compile编译主代码生成.class文件到target/classes。如果编译失败先看是不是 JDK 版本不匹配再看有没有依赖缺失。mvn test运行测试代码。默认执行src/test/java下所有符合命名规则*Test.java、Test*.java、*Tests.java的测试类。测试失败时 Maven 会直接终止构建链防止带病打包。mvn package打包。jar 项目生成 jar 包war 项目生成 war 包。关键点在于package 阶段如果项目里有测试会先跑一遍测试。如果你确定测试没有问题且想跳过比如服务器上只想快速打包可以用mvn package -DskipTests注意-DskipTests和-Dmaven.test.skiptrue有区别。前者编译测试代码但跳过执行后者直接不编译测试代码。CI 上通常用-DskipTests既保留测试代码的编译检查又节省时间。mvn install会先执行 package然后把生成的 jar 包安装到本地仓库。这样其他模块或项目在本地就能引用到这个依赖。mvn deploy把 jar 包发布到远程仓库比如 Nexus 私服。这个需要在pom.xml里配置distributionManagement同时settings.xml里配置好私服的账号密码。发布完成后团队其他成员就能通过依赖坐标拉到你发布的包。这些命令背后的生命周期关系我用一句话总结deploy包含installinstall包含packagepackage包含testtest包含compile。所以执行高阶段命令时前面所有阶段都会按顺序跑一遍。4.3 常用参数与多环境打包技巧实战中几乎每次打包都要带参数。最常用的几个-DskipTests跳过测试执行-Dmaven.test.skiptrue跳过测试编译和执行-Pprod激活 ID 为 prod 的 profile-pl module-a -am只构建指定模块及其依赖模块-T 4开启 4 线程并行构建多环境配置是部署的核心需求。开发、测试、生产环境配置往往不同传统做法是每套环境一套配置文件打包时手动改非常容易出错。Maven 的 profile 机制能优雅解决这个问题。在pom.xml里配置两个 profileprofiles profile iddev/id properties envdev/env /properties /profile profile idprod/id properties envprod/env /properties /profile /profiles然后在src/main/resources下建application-dev.yml和application-prod.yml主配置application.yml里引入spring: profiles: active: env这里的env是 Maven resource 插件的过滤占位符会在构建时被替换成 profile 里定义的值。打包时执行mvn clean package -Pprod这样打出来的包里就是生产环境配置。这个技巧我在多个项目里用过从源头解决了“忘记改配置文件”的问题。4.4 pom.xml 关键节点解读pom.xml的核心节点没几个但每个都很关键groupIdcom.example/groupId artifactIddemo-project/artifactId version1.0.0-SNAPSHOT/version packagingjar/packaginggroupId一般用公司域名倒写artifactId是项目名version是版本号。SNAPSHOT 后缀代表快照版本每次构建都可能变化适合开发阶段正式发版用1.0.0-RELEASE这种不带后缀的版本号。dependencies节点里写项目需要的所有依赖。parent节点用于继承父 POMSpring Boot 项目基本都会继承spring-boot-starter-parent它的作用是把 Spring Boot 体系内所有依赖的版本号统一管理子模块只需要声明 groupId 和 artifactId不需要写 version。build节点里是构建配置最常用的是plugins比如 Spring Boot 的spring-boot-maven-plugin它能把应用打成一个可执行 fat jarbuild plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build加了它之后mvn package打出来的 jar 里会包含所有依赖和启动脚本可以直接通过java -jar运行。不加这个插件的话普通 jar 里是不包含依赖包的运行时大概率报ClassNotFoundException。5. IDEA 与命令行配合的日常开发流5.1 IDEA 里配置 Maven 的关键注意点IDEA 自带了一个 Maven但版本可能和你项目要求的不一致。正确做法是在 IDEA 的 Settings 里手动指定我们安装的 Maven打开Settings - Build, Execution, Deployment - Build Tools - Maven填写三处Maven home path指向 Maven 安装目录User settings file指向~/.m2/settings.xmlLocal repository本地仓库路径这里有一个非常隐蔽的坑IDEA 默认的 User settings file 是~/.m2/settings.xml如果你之前没创建过这个文件IDEA 会提示找不到并回退到全局配置。有时候你以为你改了settings.xml但没生效其实就是因为 IDEA 用的不是你以为的那份文件。另一个坑在 JDK 设置。IDEA 里项目编译用的 JDK 和 Maven 运行用的 JDK 是两回事。在Settings - Build Tools - Maven - Runner里有个 JRE 选项默认是Use Project JDK如果这里选错了就可能出现你在 IDEA 里用 JDK 17 编译但 Maven 跑在 JDK 8 上导致插件报错或语法不识别。5.2 命令行构建与 IDEA 构建的冲突与选择日常开发中IDEA 的自动构建和 Maven 命令行构建经常会互相干扰。最经典的问题是你在 IDEA 里改了配置点击运行按钮前 IDEA 会自己编译一次。如果编译报错IDEA 会提示但不会告诉你 Maven 层面的问题。反过来在命令行执行mvn clean install能成功但 IDEA 里项目却报红往往是 IDEA 的缓存和索引出了问题。解决这些问题的标准姿势是两步File - Invalidate Caches清空 IDEA 缓存并重启在 IDEA 的 Maven 面板点击刷新按钮重新导入项目另外建议团队统一用 Maven 命令做最终构建IDEA 只负责日常开发和调试。CI 环境里打包路径和本地环境不同不能依赖任何 IDE 的操作。5.3 热部署场景下的 Maven 配合策略开发 Spring Boot 项目时频繁重启应用非常影响体验。引入spring-boot-devtools后热部署依赖 Maven 重新编译dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope /dependencyIDEA 里还需要开启自动编译选项Settings - Build, Execution, Deployment - Compiler - Build project automatically然后按住 CtrlShiftF9 手动重编译当前类。这里我要说一个实测经验devtools 的热部署并不是万能的。方法体内部修改可以热部署但新增方法、修改方法签名、改动配置文件这些操作大多还是需要重启。所以在实际项目里我更喜欢用 JRebel 或者在 IDEA 里直接依赖spring-boot-devtools的自动重启功能也能把大部分开发调试的等待时间省下来。6. 多模块项目拆分与依赖管理实战6.1 为什么要拆分多模块项目小项目单模块就够用了但一旦业务复杂起来单模块项目会越来越臃肿公共代码和业务代码耦合在一起接口定义和实现混在一起不同团队模块互相依赖导致频繁的代码冲突。多模块项目Multi-Module把应用拆成多个子模块父 POM 只负责统一版本管理和模块组织子模块各自管理自己的依赖。这样有几个好处公共模块独立成 jar多个业务模块复用编译时按模块依赖顺序构建增量编译更快每个模块的职责边界清晰测试和部署更精准我参与过的一个电商系统拆成了这几个模块common公共工具类、domain实体类、repository数据访问层、service业务逻辑、web接口层。每个模块都打成独立 jar上层模块依赖下层模块互不越界。6.2 父 POM 与子模块的依赖管理策略父 POM 里用modules声明子模块modules modulecommon/module moduledomain/module modulerepository/module moduleservice/module moduleweb/module /modules父 POM 的packaging必须是pom。所有子模块都要声明parent指向这个父 POM。版本管理最优雅的方式是dependencyManagement。在父 POM 里声明dependencyManagement dependencies dependency groupIdcom.example/groupId artifactIdcommon/artifactId version${project.version}/version /dependency /dependencies /dependencyManagement子模块引用时就不需要写版本号dependency groupIdcom.example/groupId artifactIdcommon/artifactId /dependency这个方式最大的好处是版本号集中在父 POM 统一管理升级依赖只改一处。这里要注意dependencyManagement和dependencies的区别前者只是统一版本信息不会引入依赖后者是实际引入依赖。6.3 按需构建指定模块多模块项目里最常见的操作是只改了一个模块不想跑全量构建。用-pl和-am控制mvn clean install -pl service -am-pl service指定构建 service 模块-am表示同时构建它依赖的模块common、domain、repository。这条命令在 CI 里特别有用能大幅缩短构建时间。注意-am是全链路上溯依赖如果一个模块被很多上层模块依赖-am会带上所有依赖链上的模块而不是只看直接依赖。理解这一点对排查构建过程中的“怎么多了几个模块”问题很有帮助。6.4 多模块项目打包与部署的衔接多模块项目最终部署时一般只需要把入口模块比如 web打出来的 jar 包拿过去部署。但有些场景下业务方要求把多个可执行模块分别部署成独立服务这时候就需要在每个可执行模块的 POM 里都配置spring-boot-maven-plugin并用finalName指定输出 jar 的名字build finalNameuser-service/finalName plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build这样mvn package之后就生成user-service.jar直接用java -jar启动即可。7. 本地部署实战把项目跑起来7.1 打包 Spring Boot 可执行 JAR 的具体过程很多初学者在mvn package成功后拿着 jar 包执行java -jar xxx.jar却报“没有主清单属性”原因就是没配置spring-boot-maven-plugin。这个插件会在打包时修改 MANIFEST.MF 文件写入入口类和 Class-Path 信息。配置正确后target目录下会生成两个 jar一个带.original后缀的普通 jar一个是可执行 fat jar。不带后缀的 fat jar 才是部署用的。如果你在 CI 上清理产物时删错文件构建就会出问题。部署阶段我一般会配合 Systemd 来做服务管理。写一个 service 单元文件[Unit] DescriptionUser Service Afternetwork.target [Service] Userdeploy ExecStart/usr/bin/java -Xms512m -Xmx1024m -jar /opt/services/user-service.jar Restarton-failure [Install] WantedBymulti-user.target使用 systemctl 管理服务线上日志通过 journalctl 查看。这套流程我用了很多年稳定可靠。7.2 依赖冲突排查的实战方法部署时遇到最多的问题就是依赖冲突。典型的报错是NoSuchMethodError: com.google.common.util.concurrent.MoreExecutors.directExecutor()这种错误通常是 guava 版本冲突导致。排查步骤mvn dependency:tree查看依赖树用-Dverbose参数查看依赖引入路径根据路径确定是哪个依赖传递进来的低版本在pom.xml里用exclusions排除dependency groupIdcom.google.guava/groupId artifactIdguava/artifactId version33.0.0-jre/version exclusions exclusion groupIdcom.google.guava/groupId artifactIdfailureaccess/artifactId /exclusion /exclusions /dependency但更推荐的做法是在dependencyManagement里统一指定 guava 版本这样所有传递依赖都会收敛到指定版本从源头上避免冲突。mvn dependency:tree是一个高频使用的命令建议所有读这篇内容的人都把它记下来。排查依赖问题、找出某个 jar 为什么被引入全指望它。7.3 远程部署与容器化的衔接方案传统部署方式是用scp把 jar 传到服务器再重启服务。实际项目里更现代化的方式是用 Docker 打包镜像。这里给一个常用的 DockerfileFROM openjdk:17-jdk-slim COPY target/user-service.jar /app/app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app/app.jar]构建镜像docker build -t user-service:1.0.0 .镜像构建好之后推到私有仓库然后在服务器上使用 docker compose 启动services: user-service: image: registry.internal/user-service:1.0.0 ports: - 8080:8080 environment: - SPRING_PROFILES_ACTIVEprod restart: alwaysMaven 与 Docker 的衔接一般有两种思路一种是在 CI 里先将 Maven 打包的 jar 作为 Docker 镜像的输入再单独执行镜像构建另一种是在pom.xml里配置dockerfile-maven-plugin让 Maven 直接输出镜像。前者灵活可控后者流程更短。我目前更推荐前者因为它把构建工具链解耦了有问题也好排查。8. 常见问题与排查技巧实录8.1 依赖下载失败或超时这是国内使用 Maven 最频繁的问题。报错一般长这样Could not transfer artifact org.springframework.boot:spring-boot-starter-web:jar:3.2.0排查顺序检查settings.xml的镜像配置是否生效mvn help:effective-settings可以查看实际生效的配置。在浏览器里访问镜像 URL确认镜像本身可用阿里云镜像偶尔也有抽风的时候可以临时切换到华为云镜像。确认本地仓库的_remote.repositories或*.lastUpdated文件是不是残留了错误状态。删掉对应目录下的.lastUpdated文件再重新拉取。很多人不知道的是Maven 默认对下载失败有缓存机制同一个文件下载失败后有一个时间窗口不会立刻重试导致“明明网络恢复了还是下载失败”的错觉。最简单的做法是直接删掉本地仓库里报错的那个目录强制重新下载。8.2 IDEA 里 Maven 配置不生效IDEA 是一个“有自己想法”的工具有时候你改了 settings.xml 它就是不认报一堆错。我的处理顺序是检查 IDEA Settings 里的 Maven home path 和 User settings file 是否指向正确点击 Maven 面板的刷新按钮File - Invalidate Caches清除缓存重启如果项目是从 Git 上拉下来的IDEA 识别 Maven 项目需要时间请耐心等右下角索引跑完。期间频繁操作可能导致索引损坏index 损坏后整个项目标红一片这时候也只能清缓存重启。还有一个常见坑IDEA 的 Maven 面板里有Reload All Maven Projects如果你改了pom.xml的依赖不用点这个按钮IDEA 会自动侦测并提示导入。但如果你手动删了本地仓库的 jarIDEA 不会自动重新下载需要手动点刷新或执行mvn clean install。8.3 打包成功但运行时找不到类这种情况太经典了。mvn package明明成功jar 也生成了运行时报ClassNotFoundException。原因通常是这个 jar 不是 fat jar。我在前面讲过必须配spring-boot-maven-plugin才会把依赖打进去。如果你已经配了插件还是报错检查一下是不是在错误的模块下执行了 package 命令——多模块项目里入口模块的插件没配置或者配置被覆盖都可能导致普通 jar 被覆盖掉可执行 jar。用jar tf命令可以快速查看 jar 包内容jar tf user-service.jar | grep Main.class如果里面有org/springframework/boot/loader/JarLauncher.class说明 fat jar 已经正确生成。8.4 老项目的 Maven 版本兼容性接手老项目时最怕的事就是版本不兼容。项目用了 Maven 3.2但你本地装了 Maven 3.9某些老插件在新版本里已经废弃构建直接挂掉。遇到这类问题第一反应不是去改代码而是找项目要求的 Maven 版本。看项目的maven-wrapper.propertiesdistributionUrlhttps://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.2.5/apache-maven-3.2.5-bin.zipMaven Wrapper 相当于是项目自带的 Maven第一次执行./mvnw会按配置自动下载对应版本之后所有构建都用这个固定版本。强烈建议所有新项目都加上 Wrapper团队协作时每个人构建环境一致能避免大量无意义的跨环境问题。8.5 常见问题速查表问题现象常见原因解决方法依赖下载超时直连中央仓库太慢配置阿里云或华为云镜像mvn -v显示版本不对JAVA_HOME 指向错误检查环境变量 JAVA_HOME打包后没有主清单属性缺少 spring-boot-maven-plugin在 pom.xml 的 build 里添加插件多模块项目引不到子模块子模块未 install 到本地仓库先执行mvn install再打包IDEA 里依赖爆红本地仓库缓存损坏清缓存重启 执行 mvn clean install构建时插件报错插件版本与 Maven 版本不兼容升级插件或切换 Maven 版本私服依赖拉不下来镜像配置劫持了私服请求修改 mirrorOf 配置排除私服 IDSNAPSHOT 版本更新后还是旧代码本地仓库有缓存删除对应 SNAPSHOT 目录或用 -U 参数9. 从本机到服务器整体部署流程复盘9.1 一次完整的部署操作顺序把本机经验迁移到服务器部署直接列出我认为最稳的流程本机执行mvn clean install -DskipTests确保所有模块能正常构建在服务器上拉取最新代码到专门的构建目录执行mvn clean package -Pprod -DskipTests确认 target 目录下生成正确的 fat jar停止旧服务如果用 systemd执行systemctl stop user-service备份旧 jarcp user-service.jar user-service.jar.bak-20250115将新 jar 拷贝到部署目录启动服务systemctl start user-service查看日志journalctl -u user-service -f确认启动成功用 curl 探测健康检查接口确认服务对外可用这个顺序看着简单但每一步都有讲究。第 1 步的意义是在本地先暴露问题别把构建错误带到服务器上第 5 到 8 步是标准发布流程先停后启能避免新旧进程抢端口。9.2 服务器构建与本地构建的差异服务器上的 Maven 环境通常比本机干净得多这反而让一些问题更容易暴露。最典型的差异是本地仓库内容的多少本机跑过大量项目本地仓库里缓存了很多依赖服务器上的本地仓库是空的第一次构建会把所有依赖全拉一遍。如果镜像配置没生效这一步就会卡很久。另一个差异是操作系统环境变量。服务器上如果通过 crontab 或者 CI Agent 执行 Maven可能没有加载~/.bashrc里的环境变量导致JAVA_HOME不存在mvn命令直接报错。这时候在脚本里显式声明环境变量export JAVA_HOME/opt/jdk-17 export PATH$JAVA_HOME/bin:$PATH export MAVEN_HOME/opt/maven export PATH$MAVEN_HOME/bin:$PATHCI 里常见的做法就是在执行 Maven 构建前先 source 一个预置的环境配置文件保证环境一致性。9.3 结合 CI 的自动化部署思路如果项目已经用 GitLab CI 或 Jenkins 做持续集成Maven 的环节通常是这样的代码提交触发流水线流水线拉取代码执行 Maven 构建mvn clean package -DskipTests将 jar 包归档到制品库触发部署任务把 jar 推送到目标服务器重启服务这个流程里 Maven 构建是核心环节其他工具都在围着它转。流水线里 Maven 这块最值得注意的配置是使用项目的 Maven Wrapper 或者固定 Maven 版本不要依赖 Agent 自带的环境。另外要单独设置一个共享的本地仓库路径避免每次构建全量拉依赖这会极大拖慢流水线耗时。我实际见过一个项目因为没共享本地仓库每次构建要拉 5 分钟依赖整个流水线要 15 分钟。加了仓库缓存之后依赖拉取降到 10 秒流水线整体降到 3 分钟。这个优化性价比极高。9.4 私有仓库Nexus在企业部署中的角色前文提到过 Nexus这里展开讲一下它和 Maven 配合的完整方案。Nexus 的核心功能是仓库管理它有三种仓库类型proxy 仓库代理远程仓库中央仓库、阿里云镜像相当于一个缓存层hosted 仓库托管团队自己发布的 jar 包包括 release 和 snapshotgroup 仓库把多个 proxy 和 hosted 聚合在一个地址下对外提供企业里的标准配置是开发人员的settings.xml里配一个mirror将所有请求指向 Nexus 的 group 仓库mirrorOf配置为*。Nexus 内部再代理阿里云镜像这样整体链路变成了本地 - Nexus - 阿里云 - 中央仓库多级缓存速度极快。团队发布 jar 包到 Nexus 时pom.xml里的distributionManagement配置distributionManagement repository idreleases/id nameInternal Releases/name urlhttp://nexus.internal/repository/maven-releases//url /repository snapshotRepository idsnapshots/id nameInternal Snapshots/name urlhttp://nexus.internal/repository/maven-snapshots//url /snapshotRepository /distributionManagement对应的settings.xml里配置账号密码servers server idreleases/id usernamedeploy/username passwordpassword/password /server server idsnapshots/id usernamedeploy/username passwordpassword/password /server /servers这个id必须完全一致否则 Maven 找不到对应的认证信息发布时会报 401。这个细节我踩过很多次坑希望你不会再踩。10. 个人实操经验总结把这几年用 Maven 的经验沉淀成几句话第一Maven 的配置问题占了日常问题的八成。学会看mvn help:effective-settings和mvn help:effective-pom能让你快速定位“实际生效的配置到底是什么”而不是凭感觉改文件。第二遇到构建问题先分清是依赖问题还是插件问题。依赖问题看dependency:tree插件问题看执行日志里报错的插件名和版本。方向对了排查速度快十倍。第三不要每次都傻傻执行mvn clean install。开发阶段用mvn compile或mvn package就够多模块项目用-pl和-am控制范围。只有在需要更新本地仓库时才需要install。养成这个习惯开发期构建时间能减少一大半。最后Maven 远不是“写几行依赖坐标”这么简单。把构建流程想清楚把仓库机制弄明白线上部署时你会少踩很多坑。希望这篇从零开始的实战内容能帮你把 Maven 这块彻底吃透。 Maven从零到实战：安装配置、依赖管理与多模块部署全攻略
Maven 这个工具但凡写过 Java 的人多少都接触过但说实话很多人在 IDEA 里一键点“刷新”之后就再也没深究过它到底在干什么。直到有一天新电脑装环境、CI 上构建失败、依赖拉不下来才意识到自己连 Maven 的安装目录在哪都说不清楚。这篇内容我就从零开始把 Maven 的安装、配置、仓库管理、常用命令、多模块部署这些环节全部过一遍包含我这些年实际踩过的坑和一直在用的配置方案希望能帮你把 Maven 这块彻底理顺。这篇内容适合谁刚接触 Java 生态、想把本地开发环境彻底搞清楚的新人也包括已经写了几个月代码、但一直靠 IDE 自动搞定依赖、想弄明白底层原理的同学。读完你至少能自己搞定 Maven 安装、配置阿里云镜像、命令行打包、多模块项目构建这些事遇到“依赖下载失败”“仓库爆红”这类问题也不会再慌。1. 内容整体设计与思路拆解1.1 Maven 到底是什么它解决了什么问题先别急着下载安装我们得先弄清楚 Maven 在 Java 生态里扮演的角色。你可以把它理解成一个“项目管家”负责三件事依赖管理、项目构建、项目信息管理。依赖管理是大多数人最先接触到的功能。以前写 Java 项目要把 jar 包手动下载下来扔进lib目录再在 IDE 里逐个添加为库。换台电脑就得重新折腾一遍团队协作时“我这边能跑你那边报错”是家常便饭。Maven 用pom.xml文件统一声明依赖坐标groupId、artifactId、version构建时自动从仓库下载对应 jar 包彻底告别手动拷贝。项目构建则是把编译、测试、打包、安装这些原本需要一串命令串联起来的步骤变成mvn clean install一句话的事。Maven 定义了标准的生命周期从 validate 到 deploy 一整套流程每个阶段绑定特定插件你只需要知道自己在哪个节点执行哪个命令就行。这两点加起来Maven 就变成了 Java 项目的事实标准。后面出现的 Gradle 虽然性能更好、写法更灵活但 Maven 的约定优于配置理念至今仍深深影响着整个 Java 构建生态。所以哪怕你现在用的是 Gradle理解 Maven 的核心理念也全是收益。1.2 为什么我要写“从零开始的实战部署”而不是单纯讲命令网上关于 Maven 的教程一搜一大把但绝大多数都停留在“怎么安装、常用命令是什么”这个层面。真正到了项目部署环节一堆实际问题就会冒出来mvn package打出来的 jar 为什么跑不起来配置文件里的仓库地址为什么不是阿里云IDEA 里明明配了 Maven 却还是用的自带版本多个项目依赖同一个 SNAPSHOT 版本为什么总是拿不到最新代码这些问题的根源其实是对 Maven 运行机制缺乏整体认知。所以这篇内容的思路是先搭好环境再讲清原理然后通过真实项目把整个构建、部署链路走一遍。你跟着操作完不仅会敲命令还能理解每条命令背后发生了什么。2. 环境准备与安装配置2.1 JDK 版本选择与安装Maven 本身是用 Java 写的运行它必须得有 JDK。先确认你本机的 Java 环境java -version这里有个容易踩的坑Maven 3.9.x 要求 JDK 8 及以上Maven 4.0 则需要 JDK 17 以上。如果你本地装的是 JDK 8就老老实实用 Maven 3.8.x 或 3.9.x别追求最新版。我见过有人在 JDK 8 的环境里强行用 Maven 4结果一堆插件不兼容构建直接崩掉。JDK 本身推荐安装 TemurinAdoptium 项目或 Amazon Corretto这两个都是 LTS 版本免费且社区活跃。别装 Oracle JDK 也行但没必要——企业里现在基本都用 OpenJDK 系。安装完成后设置好JAVA_HOME环境变量Windows 用户在系统变量的 Path 里加上%JAVA_HOME%\binmacOS/Linux 用户一般写入~/.zshrc或~/.bashrcexport JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64 export PATH$JAVA_HOME/bin:$PATH设置完记得source一下让配置生效然后重新执行java -version确认。2.2 Maven 下载安装全流程Maven 官网下载地址是maven.apache.org直接找 Latest Release 版本。建议下载apache-maven-3.9.x-bin.tar.gzLinux/macOS或apache-maven-3.9.x-bin.zipWindows不用下源码包。Windows 安装步骤解压 zip 包到指定目录比如D:\DevTools\apache-maven-3.9.9。目录路径千万别带中文和空格否则后面一堆奇怪的问题。新建环境变量MAVEN_HOME值为 Maven 解压路径。在 Path 变量中追加%MAVEN_HOME%\bin。打开新命令行窗口执行mvn -v验证。macOS 上如果你安装了 Homebrew一行命令搞定brew install maven但这里我要提醒一句通过 Homebrew 安装的 Maven 版本可能不是你想用的版本。比如你项目要求 Maven 3.8.x而 brew 默认装的是 3.9.x或更高这时候就需要手动指定版本安装或改用压缩包方式。我个人在 macOS 上还是习惯用压缩包解压到~/dev/apache-maven-3.9.9然后软链到一个固定路径这样切换版本特别方便。Linux 服务器上安装更简单一般用 wget 下载解压wget https://archive.apache.org/dist/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt ln -s /opt/apache-maven-3.9.9 /opt/maven然后把/opt/maven/bin加到 PATH 里。2.3 验证安装与检查配置是否生效安装完成后执行mvn -v输出应该类似Apache Maven 3.9.9 (8e9479a3f1f095c56d2e8f5e2f5e0c0f0e0c0f0) Maven home: /opt/maven Java version: 17.0.11, vendor: Eclipse Adoptium Runtime: /usr/lib/jvm/java-17-openjdk-amd64注意看 Maven home 和 Java version 这两行。如果 Java version 显示的不是你期望的版本说明JAVA_HOME环境变量没配对或者 IDE 里单独指定了 JDK 版本。这个问题在 IDEA 里特别常见后面我会专门讲。3. 核心配置文件与仓库机制详解3.1 settings.xml全局配置与用户配置Maven 有两份settings.xml一份在 Maven 安装目录的conf/下叫全局配置另一份在~/.m2/目录下叫用户配置。两者的优先级是用户配置覆盖全局配置。实际使用中建议改用户配置那份不要动全局配置不然升级 Maven 版本时改动会被覆盖。settings.xml里我几乎每次都要动几个地方localRepository本地仓库路径、mirror镜像配置、profile激活特定仓库或属性。下面这份是我在服务器上的常用配置骨架settings localRepository/opt/maven-repo/localRepository mirrors mirror idaliyun-central/id mirrorOfcentral/mirrorOf name阿里云中央仓库镜像/name urlhttps://maven.aliyun.com/repository/central/url /mirror /mirrors profiles profile idaliyun/id repositories repository idaliyun-public/id urlhttps://maven.aliyun.com/repository/public/url releasesenabledtrue/enabled/releases snapshotsenabledtrue/enabled/snapshots /repository /repositories /profile /profiles activeProfiles activeProfilealiyun/activeProfile /activeProfiles /settings这段配置里的mirror会把所有对中央仓库的请求转发到阿里云镜像profile则补充了阿里云的 public 仓库里面聚合了中央仓库和常用的第三方仓库对国内网络环境特别友好。3.2 本地仓库、中央仓库与镜像的关系很多新手分不清这三个概念。我打个比方本地仓库是你自己电脑上的“零食柜”中央仓库是网上的“大超市”镜像就是超市在你小区门口设的“自提点”。当你执行mvn dependency:resolve时Maven 会先看本地仓库有没有这个依赖有就直接用没有就去配置的远程仓库下载。默认的远程仓库是中央仓库repo.maven.apache.org但国内直连它经常超时或龟速。这时候配一个阿里云镜像就相当于小区门口的“自提点”下载速度快得多。还有一个关键细节本地仓库路径不需要手动建Maven 首次执行时会自动创建。但如果你改了localRepository指向一个不存在的路径Maven 也会自动建。唯一要注意的是磁盘空间——我见过于依赖本地仓库里积累了十几个G的旧包建议定期清理~/.m2/repository下那些长时间没用的 SNAPSHOT 版本。3.3 本地仓库与依赖下载的完整流程看一个真实的依赖下载过程。新建一个空项目pom.xml里只声明一个依赖dependency groupIdcom.google.guava/groupId artifactIdguava/artifactId version33.0.0-jre/version /dependency然后执行mvn dependency:resolve你会看到控制台输出了下载日志下载完成后在本地仓库的对应路径下会出现guava-33.0.0-jre.jar和同名.pom文件。Maven 下载依赖不仅仅是 jar 包还有它对应的 POM 文件因为 POM 文件里声明了这个依赖自身的传递性依赖。所以 Guava 的 jar 下载完后它依赖的failureaccess、listenablefuture这些包也会被跟着拉下来。这就是 Maven 依赖传递机制的体现。你不需要显式声明每个依赖的依赖Maven 会根据 POM 文件自动推导。但传递依赖也会引入一个问题版本冲突。当两个依赖传递到同一个库的不同版本时Maven 采用“最短路径优先”原则如果路径深度相同则先声明者优先。这个规则经常导致“我明明引了高版本为什么进来的是低版本”的困惑。3.4 阿里云镜像配置与多镜像仓库的取舍现在几乎所有国内 Java 团队都在用阿里云镜像。配置很简单在settings.xml的mirrors节点里加一段即可mirror idaliyun/id mirrorOf*/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror这里mirrorOf的值有讲究。*表示所有仓库请求都走这个镜像包括你自己在项目里配置的私有仓库。如果你公司内部有私服比如 Nexus千万别用*要写成central或者用external:*排除本地仓库。我见过有人图省事配了*结果私服的包怎么也拉不下来排查半天才发现是镜像把私服请求也劫持了。多镜像仓库场景下mirrorOf还支持逗号分隔多个仓库 ID比如mirrorOfcentral,my-repo/mirrorOf但实际项目中更推荐的做法是用 Nexus 作为私服私服上面配置代理仓库把阿里云镜像和中央仓库都代理一遍。这样团队内部所有依赖都从私服走既快又可控还能统一管理第三方上传的包。这个方案我会在后面的部署实战里具体展开。4. 命令行实操与生命周期详解4.1 从零搭建一个标准 Maven 项目跑命令之前得有项目。最正统的方式是用 Maven 原型生成mvn archetype:generate -DgroupIdcom.example -DartifactIddemo-project -DarchetypeArtifactIdmaven-archetype-quickstart -DinteractiveModefalse这条命令会生成一个标准目录结构demo-project ├── pom.xml └── src ├── main │ └── java/com/example/App.java └── test └── java/com/example/AppTest.java现在实际项目更常用的做法是去 start.spring.io 初始化一个 Spring Boot 项目或者直接用 IDEA 的 Spring Initializr。但我还是建议新手手工建一次目录能帮你真正理解 Maven 的约定src/main/java是主代码src/test/java是测试代码target是构建输出目录。这些目录都是在 POM 里配置的但 Maven 默认就这么规定除非有特殊需求否则大家都遵守这个约定。4.2 核心命令逐个拆解clean、compile、test、package、install、deploymvn clean删除 target 目录。为什么不直接 build 而要先 clean因为 Maven 默认不会自动清理旧的 class 文件和资源增量构建可能把上一次编译残留的 class 带进来导致“改了代码但跑起来还是旧的”这种灵异问题。所以 CI 里一般都会先 clean 再 build。mvn compile编译主代码生成.class文件到target/classes。如果编译失败先看是不是 JDK 版本不匹配再看有没有依赖缺失。mvn test运行测试代码。默认执行src/test/java下所有符合命名规则*Test.java、Test*.java、*Tests.java的测试类。测试失败时 Maven 会直接终止构建链防止带病打包。mvn package打包。jar 项目生成 jar 包war 项目生成 war 包。关键点在于package 阶段如果项目里有测试会先跑一遍测试。如果你确定测试没有问题且想跳过比如服务器上只想快速打包可以用mvn package -DskipTests注意-DskipTests和-Dmaven.test.skiptrue有区别。前者编译测试代码但跳过执行后者直接不编译测试代码。CI 上通常用-DskipTests既保留测试代码的编译检查又节省时间。mvn install会先执行 package然后把生成的 jar 包安装到本地仓库。这样其他模块或项目在本地就能引用到这个依赖。mvn deploy把 jar 包发布到远程仓库比如 Nexus 私服。这个需要在pom.xml里配置distributionManagement同时settings.xml里配置好私服的账号密码。发布完成后团队其他成员就能通过依赖坐标拉到你发布的包。这些命令背后的生命周期关系我用一句话总结deploy包含installinstall包含packagepackage包含testtest包含compile。所以执行高阶段命令时前面所有阶段都会按顺序跑一遍。4.3 常用参数与多环境打包技巧实战中几乎每次打包都要带参数。最常用的几个-DskipTests跳过测试执行-Dmaven.test.skiptrue跳过测试编译和执行-Pprod激活 ID 为 prod 的 profile-pl module-a -am只构建指定模块及其依赖模块-T 4开启 4 线程并行构建多环境配置是部署的核心需求。开发、测试、生产环境配置往往不同传统做法是每套环境一套配置文件打包时手动改非常容易出错。Maven 的 profile 机制能优雅解决这个问题。在pom.xml里配置两个 profileprofiles profile iddev/id properties envdev/env /properties /profile profile idprod/id properties envprod/env /properties /profile /profiles然后在src/main/resources下建application-dev.yml和application-prod.yml主配置application.yml里引入spring: profiles: active: env这里的env是 Maven resource 插件的过滤占位符会在构建时被替换成 profile 里定义的值。打包时执行mvn clean package -Pprod这样打出来的包里就是生产环境配置。这个技巧我在多个项目里用过从源头解决了“忘记改配置文件”的问题。4.4 pom.xml 关键节点解读pom.xml的核心节点没几个但每个都很关键groupIdcom.example/groupId artifactIddemo-project/artifactId version1.0.0-SNAPSHOT/version packagingjar/packaginggroupId一般用公司域名倒写artifactId是项目名version是版本号。SNAPSHOT 后缀代表快照版本每次构建都可能变化适合开发阶段正式发版用1.0.0-RELEASE这种不带后缀的版本号。dependencies节点里写项目需要的所有依赖。parent节点用于继承父 POMSpring Boot 项目基本都会继承spring-boot-starter-parent它的作用是把 Spring Boot 体系内所有依赖的版本号统一管理子模块只需要声明 groupId 和 artifactId不需要写 version。build节点里是构建配置最常用的是plugins比如 Spring Boot 的spring-boot-maven-plugin它能把应用打成一个可执行 fat jarbuild plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build加了它之后mvn package打出来的 jar 里会包含所有依赖和启动脚本可以直接通过java -jar运行。不加这个插件的话普通 jar 里是不包含依赖包的运行时大概率报ClassNotFoundException。5. IDEA 与命令行配合的日常开发流5.1 IDEA 里配置 Maven 的关键注意点IDEA 自带了一个 Maven但版本可能和你项目要求的不一致。正确做法是在 IDEA 的 Settings 里手动指定我们安装的 Maven打开Settings - Build, Execution, Deployment - Build Tools - Maven填写三处Maven home path指向 Maven 安装目录User settings file指向~/.m2/settings.xmlLocal repository本地仓库路径这里有一个非常隐蔽的坑IDEA 默认的 User settings file 是~/.m2/settings.xml如果你之前没创建过这个文件IDEA 会提示找不到并回退到全局配置。有时候你以为你改了settings.xml但没生效其实就是因为 IDEA 用的不是你以为的那份文件。另一个坑在 JDK 设置。IDEA 里项目编译用的 JDK 和 Maven 运行用的 JDK 是两回事。在Settings - Build Tools - Maven - Runner里有个 JRE 选项默认是Use Project JDK如果这里选错了就可能出现你在 IDEA 里用 JDK 17 编译但 Maven 跑在 JDK 8 上导致插件报错或语法不识别。5.2 命令行构建与 IDEA 构建的冲突与选择日常开发中IDEA 的自动构建和 Maven 命令行构建经常会互相干扰。最经典的问题是你在 IDEA 里改了配置点击运行按钮前 IDEA 会自己编译一次。如果编译报错IDEA 会提示但不会告诉你 Maven 层面的问题。反过来在命令行执行mvn clean install能成功但 IDEA 里项目却报红往往是 IDEA 的缓存和索引出了问题。解决这些问题的标准姿势是两步File - Invalidate Caches清空 IDEA 缓存并重启在 IDEA 的 Maven 面板点击刷新按钮重新导入项目另外建议团队统一用 Maven 命令做最终构建IDEA 只负责日常开发和调试。CI 环境里打包路径和本地环境不同不能依赖任何 IDE 的操作。5.3 热部署场景下的 Maven 配合策略开发 Spring Boot 项目时频繁重启应用非常影响体验。引入spring-boot-devtools后热部署依赖 Maven 重新编译dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope /dependencyIDEA 里还需要开启自动编译选项Settings - Build, Execution, Deployment - Compiler - Build project automatically然后按住 CtrlShiftF9 手动重编译当前类。这里我要说一个实测经验devtools 的热部署并不是万能的。方法体内部修改可以热部署但新增方法、修改方法签名、改动配置文件这些操作大多还是需要重启。所以在实际项目里我更喜欢用 JRebel 或者在 IDEA 里直接依赖spring-boot-devtools的自动重启功能也能把大部分开发调试的等待时间省下来。6. 多模块项目拆分与依赖管理实战6.1 为什么要拆分多模块项目小项目单模块就够用了但一旦业务复杂起来单模块项目会越来越臃肿公共代码和业务代码耦合在一起接口定义和实现混在一起不同团队模块互相依赖导致频繁的代码冲突。多模块项目Multi-Module把应用拆成多个子模块父 POM 只负责统一版本管理和模块组织子模块各自管理自己的依赖。这样有几个好处公共模块独立成 jar多个业务模块复用编译时按模块依赖顺序构建增量编译更快每个模块的职责边界清晰测试和部署更精准我参与过的一个电商系统拆成了这几个模块common公共工具类、domain实体类、repository数据访问层、service业务逻辑、web接口层。每个模块都打成独立 jar上层模块依赖下层模块互不越界。6.2 父 POM 与子模块的依赖管理策略父 POM 里用modules声明子模块modules modulecommon/module moduledomain/module modulerepository/module moduleservice/module moduleweb/module /modules父 POM 的packaging必须是pom。所有子模块都要声明parent指向这个父 POM。版本管理最优雅的方式是dependencyManagement。在父 POM 里声明dependencyManagement dependencies dependency groupIdcom.example/groupId artifactIdcommon/artifactId version${project.version}/version /dependency /dependencies /dependencyManagement子模块引用时就不需要写版本号dependency groupIdcom.example/groupId artifactIdcommon/artifactId /dependency这个方式最大的好处是版本号集中在父 POM 统一管理升级依赖只改一处。这里要注意dependencyManagement和dependencies的区别前者只是统一版本信息不会引入依赖后者是实际引入依赖。6.3 按需构建指定模块多模块项目里最常见的操作是只改了一个模块不想跑全量构建。用-pl和-am控制mvn clean install -pl service -am-pl service指定构建 service 模块-am表示同时构建它依赖的模块common、domain、repository。这条命令在 CI 里特别有用能大幅缩短构建时间。注意-am是全链路上溯依赖如果一个模块被很多上层模块依赖-am会带上所有依赖链上的模块而不是只看直接依赖。理解这一点对排查构建过程中的“怎么多了几个模块”问题很有帮助。6.4 多模块项目打包与部署的衔接多模块项目最终部署时一般只需要把入口模块比如 web打出来的 jar 包拿过去部署。但有些场景下业务方要求把多个可执行模块分别部署成独立服务这时候就需要在每个可执行模块的 POM 里都配置spring-boot-maven-plugin并用finalName指定输出 jar 的名字build finalNameuser-service/finalName plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build这样mvn package之后就生成user-service.jar直接用java -jar启动即可。7. 本地部署实战把项目跑起来7.1 打包 Spring Boot 可执行 JAR 的具体过程很多初学者在mvn package成功后拿着 jar 包执行java -jar xxx.jar却报“没有主清单属性”原因就是没配置spring-boot-maven-plugin。这个插件会在打包时修改 MANIFEST.MF 文件写入入口类和 Class-Path 信息。配置正确后target目录下会生成两个 jar一个带.original后缀的普通 jar一个是可执行 fat jar。不带后缀的 fat jar 才是部署用的。如果你在 CI 上清理产物时删错文件构建就会出问题。部署阶段我一般会配合 Systemd 来做服务管理。写一个 service 单元文件[Unit] DescriptionUser Service Afternetwork.target [Service] Userdeploy ExecStart/usr/bin/java -Xms512m -Xmx1024m -jar /opt/services/user-service.jar Restarton-failure [Install] WantedBymulti-user.target使用 systemctl 管理服务线上日志通过 journalctl 查看。这套流程我用了很多年稳定可靠。7.2 依赖冲突排查的实战方法部署时遇到最多的问题就是依赖冲突。典型的报错是NoSuchMethodError: com.google.common.util.concurrent.MoreExecutors.directExecutor()这种错误通常是 guava 版本冲突导致。排查步骤mvn dependency:tree查看依赖树用-Dverbose参数查看依赖引入路径根据路径确定是哪个依赖传递进来的低版本在pom.xml里用exclusions排除dependency groupIdcom.google.guava/groupId artifactIdguava/artifactId version33.0.0-jre/version exclusions exclusion groupIdcom.google.guava/groupId artifactIdfailureaccess/artifactId /exclusion /exclusions /dependency但更推荐的做法是在dependencyManagement里统一指定 guava 版本这样所有传递依赖都会收敛到指定版本从源头上避免冲突。mvn dependency:tree是一个高频使用的命令建议所有读这篇内容的人都把它记下来。排查依赖问题、找出某个 jar 为什么被引入全指望它。7.3 远程部署与容器化的衔接方案传统部署方式是用scp把 jar 传到服务器再重启服务。实际项目里更现代化的方式是用 Docker 打包镜像。这里给一个常用的 DockerfileFROM openjdk:17-jdk-slim COPY target/user-service.jar /app/app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app/app.jar]构建镜像docker build -t user-service:1.0.0 .镜像构建好之后推到私有仓库然后在服务器上使用 docker compose 启动services: user-service: image: registry.internal/user-service:1.0.0 ports: - 8080:8080 environment: - SPRING_PROFILES_ACTIVEprod restart: alwaysMaven 与 Docker 的衔接一般有两种思路一种是在 CI 里先将 Maven 打包的 jar 作为 Docker 镜像的输入再单独执行镜像构建另一种是在pom.xml里配置dockerfile-maven-plugin让 Maven 直接输出镜像。前者灵活可控后者流程更短。我目前更推荐前者因为它把构建工具链解耦了有问题也好排查。8. 常见问题与排查技巧实录8.1 依赖下载失败或超时这是国内使用 Maven 最频繁的问题。报错一般长这样Could not transfer artifact org.springframework.boot:spring-boot-starter-web:jar:3.2.0排查顺序检查settings.xml的镜像配置是否生效mvn help:effective-settings可以查看实际生效的配置。在浏览器里访问镜像 URL确认镜像本身可用阿里云镜像偶尔也有抽风的时候可以临时切换到华为云镜像。确认本地仓库的_remote.repositories或*.lastUpdated文件是不是残留了错误状态。删掉对应目录下的.lastUpdated文件再重新拉取。很多人不知道的是Maven 默认对下载失败有缓存机制同一个文件下载失败后有一个时间窗口不会立刻重试导致“明明网络恢复了还是下载失败”的错觉。最简单的做法是直接删掉本地仓库里报错的那个目录强制重新下载。8.2 IDEA 里 Maven 配置不生效IDEA 是一个“有自己想法”的工具有时候你改了 settings.xml 它就是不认报一堆错。我的处理顺序是检查 IDEA Settings 里的 Maven home path 和 User settings file 是否指向正确点击 Maven 面板的刷新按钮File - Invalidate Caches清除缓存重启如果项目是从 Git 上拉下来的IDEA 识别 Maven 项目需要时间请耐心等右下角索引跑完。期间频繁操作可能导致索引损坏index 损坏后整个项目标红一片这时候也只能清缓存重启。还有一个常见坑IDEA 的 Maven 面板里有Reload All Maven Projects如果你改了pom.xml的依赖不用点这个按钮IDEA 会自动侦测并提示导入。但如果你手动删了本地仓库的 jarIDEA 不会自动重新下载需要手动点刷新或执行mvn clean install。8.3 打包成功但运行时找不到类这种情况太经典了。mvn package明明成功jar 也生成了运行时报ClassNotFoundException。原因通常是这个 jar 不是 fat jar。我在前面讲过必须配spring-boot-maven-plugin才会把依赖打进去。如果你已经配了插件还是报错检查一下是不是在错误的模块下执行了 package 命令——多模块项目里入口模块的插件没配置或者配置被覆盖都可能导致普通 jar 被覆盖掉可执行 jar。用jar tf命令可以快速查看 jar 包内容jar tf user-service.jar | grep Main.class如果里面有org/springframework/boot/loader/JarLauncher.class说明 fat jar 已经正确生成。8.4 老项目的 Maven 版本兼容性接手老项目时最怕的事就是版本不兼容。项目用了 Maven 3.2但你本地装了 Maven 3.9某些老插件在新版本里已经废弃构建直接挂掉。遇到这类问题第一反应不是去改代码而是找项目要求的 Maven 版本。看项目的maven-wrapper.propertiesdistributionUrlhttps://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.2.5/apache-maven-3.2.5-bin.zipMaven Wrapper 相当于是项目自带的 Maven第一次执行./mvnw会按配置自动下载对应版本之后所有构建都用这个固定版本。强烈建议所有新项目都加上 Wrapper团队协作时每个人构建环境一致能避免大量无意义的跨环境问题。8.5 常见问题速查表问题现象常见原因解决方法依赖下载超时直连中央仓库太慢配置阿里云或华为云镜像mvn -v显示版本不对JAVA_HOME 指向错误检查环境变量 JAVA_HOME打包后没有主清单属性缺少 spring-boot-maven-plugin在 pom.xml 的 build 里添加插件多模块项目引不到子模块子模块未 install 到本地仓库先执行mvn install再打包IDEA 里依赖爆红本地仓库缓存损坏清缓存重启 执行 mvn clean install构建时插件报错插件版本与 Maven 版本不兼容升级插件或切换 Maven 版本私服依赖拉不下来镜像配置劫持了私服请求修改 mirrorOf 配置排除私服 IDSNAPSHOT 版本更新后还是旧代码本地仓库有缓存删除对应 SNAPSHOT 目录或用 -U 参数9. 从本机到服务器整体部署流程复盘9.1 一次完整的部署操作顺序把本机经验迁移到服务器部署直接列出我认为最稳的流程本机执行mvn clean install -DskipTests确保所有模块能正常构建在服务器上拉取最新代码到专门的构建目录执行mvn clean package -Pprod -DskipTests确认 target 目录下生成正确的 fat jar停止旧服务如果用 systemd执行systemctl stop user-service备份旧 jarcp user-service.jar user-service.jar.bak-20250115将新 jar 拷贝到部署目录启动服务systemctl start user-service查看日志journalctl -u user-service -f确认启动成功用 curl 探测健康检查接口确认服务对外可用这个顺序看着简单但每一步都有讲究。第 1 步的意义是在本地先暴露问题别把构建错误带到服务器上第 5 到 8 步是标准发布流程先停后启能避免新旧进程抢端口。9.2 服务器构建与本地构建的差异服务器上的 Maven 环境通常比本机干净得多这反而让一些问题更容易暴露。最典型的差异是本地仓库内容的多少本机跑过大量项目本地仓库里缓存了很多依赖服务器上的本地仓库是空的第一次构建会把所有依赖全拉一遍。如果镜像配置没生效这一步就会卡很久。另一个差异是操作系统环境变量。服务器上如果通过 crontab 或者 CI Agent 执行 Maven可能没有加载~/.bashrc里的环境变量导致JAVA_HOME不存在mvn命令直接报错。这时候在脚本里显式声明环境变量export JAVA_HOME/opt/jdk-17 export PATH$JAVA_HOME/bin:$PATH export MAVEN_HOME/opt/maven export PATH$MAVEN_HOME/bin:$PATHCI 里常见的做法就是在执行 Maven 构建前先 source 一个预置的环境配置文件保证环境一致性。9.3 结合 CI 的自动化部署思路如果项目已经用 GitLab CI 或 Jenkins 做持续集成Maven 的环节通常是这样的代码提交触发流水线流水线拉取代码执行 Maven 构建mvn clean package -DskipTests将 jar 包归档到制品库触发部署任务把 jar 推送到目标服务器重启服务这个流程里 Maven 构建是核心环节其他工具都在围着它转。流水线里 Maven 这块最值得注意的配置是使用项目的 Maven Wrapper 或者固定 Maven 版本不要依赖 Agent 自带的环境。另外要单独设置一个共享的本地仓库路径避免每次构建全量拉依赖这会极大拖慢流水线耗时。我实际见过一个项目因为没共享本地仓库每次构建要拉 5 分钟依赖整个流水线要 15 分钟。加了仓库缓存之后依赖拉取降到 10 秒流水线整体降到 3 分钟。这个优化性价比极高。9.4 私有仓库Nexus在企业部署中的角色前文提到过 Nexus这里展开讲一下它和 Maven 配合的完整方案。Nexus 的核心功能是仓库管理它有三种仓库类型proxy 仓库代理远程仓库中央仓库、阿里云镜像相当于一个缓存层hosted 仓库托管团队自己发布的 jar 包包括 release 和 snapshotgroup 仓库把多个 proxy 和 hosted 聚合在一个地址下对外提供企业里的标准配置是开发人员的settings.xml里配一个mirror将所有请求指向 Nexus 的 group 仓库mirrorOf配置为*。Nexus 内部再代理阿里云镜像这样整体链路变成了本地 - Nexus - 阿里云 - 中央仓库多级缓存速度极快。团队发布 jar 包到 Nexus 时pom.xml里的distributionManagement配置distributionManagement repository idreleases/id nameInternal Releases/name urlhttp://nexus.internal/repository/maven-releases//url /repository snapshotRepository idsnapshots/id nameInternal Snapshots/name urlhttp://nexus.internal/repository/maven-snapshots//url /snapshotRepository /distributionManagement对应的settings.xml里配置账号密码servers server idreleases/id usernamedeploy/username passwordpassword/password /server server idsnapshots/id usernamedeploy/username passwordpassword/password /server /servers这个id必须完全一致否则 Maven 找不到对应的认证信息发布时会报 401。这个细节我踩过很多次坑希望你不会再踩。10. 个人实操经验总结把这几年用 Maven 的经验沉淀成几句话第一Maven 的配置问题占了日常问题的八成。学会看mvn help:effective-settings和mvn help:effective-pom能让你快速定位“实际生效的配置到底是什么”而不是凭感觉改文件。第二遇到构建问题先分清是依赖问题还是插件问题。依赖问题看dependency:tree插件问题看执行日志里报错的插件名和版本。方向对了排查速度快十倍。第三不要每次都傻傻执行mvn clean install。开发阶段用mvn compile或mvn package就够多模块项目用-pl和-am控制范围。只有在需要更新本地仓库时才需要install。养成这个习惯开发期构建时间能减少一大半。最后Maven 远不是“写几行依赖坐标”这么简单。把构建流程想清楚把仓库机制弄明白线上部署时你会少踩很多坑。希望这篇从零开始的实战内容能帮你把 Maven 这块彻底吃透。