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 本身推荐安装 Temurin（Adoptium 项目）或 Amazon Corretto，这两个都是 LTS 版本，免费且社区活跃。别装 Oracle JDK 也行，但没必要——企业里现在基本都用 OpenJDK 系。

安装完成后设置好JAVA_HOME环境变量，Windows 用户在系统变量的 Path 里加上%JAVA_HOME%\bin，macOS/Linux 用户一般写入~/.zshrc或~/.bashrc：

export 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.gz（Linux/macOS）或apache-maven-3.9.x-bin.zip（Windows），不用下源码包。

Windows 安装步骤：

1. 解压 zip 包到指定目录，比如D:\DevTools\apache-maven-3.9.9。目录路径千万别带中文和空格，否则后面一堆奇怪的问题。
2. 新建环境变量MAVEN_HOME，值为 Maven 解压路径。
3. 在 Path 变量中追加%MAVEN_HOME%\bin。
4. 打开新命令行窗口，执行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> <id>aliyun-central</id> <mirrorOf>central</mirrorOf> <name>阿里云中央仓库镜像</name> <url>https://maven.aliyun.com/repository/central</url> </mirror> </mirrors> <profiles> <profile> <id>aliyun</id> <repositories> <repository> <id>aliyun-public</id> <url>https://maven.aliyun.com/repository/public</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>true</enabled></snapshots> </repository> </repositories> </profile> </profiles> <activeProfiles> <activeProfile>aliyun</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> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>33.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> <id>aliyun</id> <mirrorOf>*</mirrorOf> <url>https://maven.aliyun.com/repository/public</url> </mirror>

这里mirrorOf的值有讲究。*表示所有仓库请求都走这个镜像，包括你自己在项目里配置的私有仓库。如果你公司内部有私服（比如 Nexus），千万别用*，要写成central或者用external:*排除本地仓库。我见过有人图省事配了*，结果私服的包怎么也拉不下来，排查半天才发现是镜像把私服请求也劫持了。

多镜像仓库场景下，mirrorOf还支持逗号分隔多个仓库 ID，比如：

<mirrorOf>central,my-repo</mirrorOf>

但实际项目中更推荐的做法是：用 Nexus 作为私服，私服上面配置代理仓库，把阿里云镜像和中央仓库都代理一遍。这样团队内部所有依赖都从私服走，既快又可控，还能统一管理第三方上传的包。这个方案我会在后面的部署实战里具体展开。

4. 命令行实操与生命周期详解

4.1 从零搭建一个标准 Maven 项目

跑命令之前，得有项目。最正统的方式是用 Maven 原型生成：

mvn archetype:generate -DgroupId=com.example -DartifactId=demo-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

这条命令会生成一个标准目录结构：

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、deploy

mvn 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.skip=true有区别。前者编译测试代码但跳过执行，后者直接不编译测试代码。CI 上通常用-DskipTests，既保留测试代码的编译检查，又节省时间。

mvn install：会先执行 package，然后把生成的 jar 包安装到本地仓库。这样其他模块或项目在本地就能引用到这个依赖。

mvn deploy：把 jar 包发布到远程仓库（比如 Nexus 私服）。这个需要在pom.xml里配置distributionManagement，同时settings.xml里配置好私服的账号密码。发布完成后，团队其他成员就能通过依赖坐标拉到你发布的包。

这些命令背后的生命周期关系我用一句话总结：deploy包含install，install包含package，package包含test，test包含compile。所以执行高阶段命令时，前面所有阶段都会按顺序跑一遍。

4.3 常用参数与多环境打包技巧

实战中几乎每次打包都要带参数。最常用的几个：

• -DskipTests：跳过测试执行
• -Dmaven.test.skip=true：跳过测试编译和执行
• -Pprod：激活 ID 为 prod 的 profile
• -pl module-a -am：只构建指定模块及其依赖模块
• -T 4：开启 4 线程并行构建

多环境配置是部署的核心需求。开发、测试、生产环境配置往往不同，传统做法是每套环境一套配置文件，打包时手动改，非常容易出错。Maven 的 profile 机制能优雅解决这个问题。

在pom.xml里配置两个 profile：

<profiles> <profile> <id>dev</id> <properties> <env>dev</env> </properties> </profile> <profile> <id>prod</id> <properties> <env>prod</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的核心节点没几个，但每个都很关键：

<groupId>com.example</groupId> <artifactId>demo-project</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>jar</packaging>

groupId一般用公司域名倒写，artifactId是项目名，version是版本号。SNAPSHOT 后缀代表快照版本，每次构建都可能变化，适合开发阶段；正式发版用1.0.0-RELEASE这种不带后缀的版本号。

dependencies节点里写项目需要的所有依赖。parent节点用于继承父 POM，Spring Boot 项目基本都会继承spring-boot-starter-parent，它的作用是把 Spring Boot 体系内所有依赖的版本号统一管理，子模块只需要声明 groupId 和 artifactId，不需要写 version。

build节点里是构建配置，最常用的是plugins，比如 Spring Boot 的spring-boot-maven-plugin，它能把应用打成一个可执行 fat jar：

<build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-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.xml
• Local 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 的缓存和索引出了问题。

解决这些问题的标准姿势是两步：

1. File -> Invalidate Caches清空 IDEA 缓存并重启
2. 在 IDEA 的 Maven 面板点击刷新按钮，重新导入项目

另外建议团队统一用 Maven 命令做最终构建，IDEA 只负责日常开发和调试。CI 环境里打包路径和本地环境不同，不能依赖任何 IDE 的操作。

5.3 热部署场景下的 Maven 配合策略

开发 Spring Boot 项目时，频繁重启应用非常影响体验。引入spring-boot-devtools后，热部署依赖 Maven 重新编译：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <scope>runtime</scope> </dependency>

IDEA 里还需要开启自动编译选项：Settings -> Build, Execution, Deployment -> Compiler -> Build project automatically，然后按住 Ctrl+Shift+F9 手动重编译当前类。

这里我要说一个实测经验：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> <module>common</module> <module>domain</module> <module>repository</module> <module>service</module> <module>web</module> </modules>

父 POM 的packaging必须是pom。所有子模块都要声明<parent>指向这个父 POM。

版本管理最优雅的方式是dependencyManagement。在父 POM 里声明：

<dependencyManagement> <dependencies> <dependency> <groupId>com.example</groupId> <artifactId>common</artifactId> <version>${project.version}</version> </dependency> </dependencies> </dependencyManagement>

子模块引用时就不需要写版本号：

<dependency> <groupId>com.example</groupId> <artifactId>common</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> <finalName>user-service</finalName> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-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] Description=User Service After=network.target [Service] User=deploy ExecStart=/usr/bin/java -Xms512m -Xmx1024m -jar /opt/services/user-service.jar Restart=on-failure [Install] WantedBy=multi-user.target

使用 systemctl 管理服务，线上日志通过 journalctl 查看。这套流程我用了很多年，稳定可靠。

7.2 依赖冲突排查的实战方法

部署时遇到最多的问题就是依赖冲突。典型的报错是：

NoSuchMethodError: com.google.common.util.concurrent.MoreExecutors.directExecutor()

这种错误通常是 guava 版本冲突导致。排查步骤：

1. mvn dependency:tree查看依赖树
2. 用-Dverbose参数查看依赖引入路径
3. 根据路径确定是哪个依赖传递进来的低版本，在pom.xml里用<exclusions>排除

<dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>33.0.0-jre</version> <exclusions> <exclusion> <groupId>com.google.guava</groupId> <artifactId>failureaccess</artifactId> </exclusion> </exclusions> </dependency>

但更推荐的做法是在dependencyManagement里统一指定 guava 版本，这样所有传递依赖都会收敛到指定版本，从源头上避免冲突。

mvn dependency:tree是一个高频使用的命令，建议所有读这篇内容的人都把它记下来。排查依赖问题、找出某个 jar 为什么被引入，全指望它。

7.3 远程部署与容器化的衔接方案

传统部署方式是用scp把 jar 传到服务器再重启服务。实际项目里更现代化的方式是用 Docker 打包镜像。这里给一个常用的 Dockerfile：

FROM 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_ACTIVE=prod restart: always

Maven 与 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

排查顺序：

1. 检查settings.xml的镜像配置是否生效，mvn help:effective-settings可以查看实际生效的配置。
2. 在浏览器里访问镜像 URL，确认镜像本身可用，阿里云镜像偶尔也有抽风的时候，可以临时切换到华为云镜像。
3. 确认本地仓库的_remote.repositories或*.lastUpdated文件是不是残留了错误状态。删掉对应目录下的.lastUpdated文件再重新拉取。

很多人不知道的是，Maven 默认对下载失败有缓存机制，同一个文件下载失败后有一个时间窗口不会立刻重试，导致“明明网络恢复了还是下载失败”的错觉。最简单的做法是直接删掉本地仓库里报错的那个目录，强制重新下载。

8.2 IDEA 里 Maven 配置不生效

IDEA 是一个“有自己想法”的工具，有时候你改了 settings.xml 它就是不认，报一堆错。我的处理顺序是：

1. 检查 IDEA Settings 里的 Maven home path 和 User settings file 是否指向正确
2. 点击 Maven 面板的刷新按钮
3. File -> Invalidate Caches清除缓存重启

如果项目是从 Git 上拉下来的，IDEA 识别 Maven 项目需要时间，请耐心等右下角索引跑完。期间频繁操作可能导致索引损坏，index 损坏后整个项目标红一片，这时候也只能清缓存重启。

还有一个常见坑：IDEA 的 Maven 面板里有Reload All Maven Projects，如果你改了pom.xml的依赖，不用点这个按钮，IDEA 会自动侦测并提示导入。但如果你手动删了本地仓库的 jar，IDEA 不会自动重新下载，需要手动点刷新或执行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.properties：

distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.2.5/apache-maven-3.2.5-bin.zip

Maven Wrapper 相当于是项目自带的 Maven，第一次执行./mvnw会按配置自动下载对应版本，之后所有构建都用这个固定版本。强烈建议所有新项目都加上 Wrapper，团队协作时每个人构建环境一致，能避免大量无意义的跨环境问题。

8.5 常见问题速查表

9. 从本机到服务器：整体部署流程复盘

9.1 一次完整的部署操作顺序

把本机经验迁移到服务器部署，直接列出我认为最稳的流程：

1. 本机执行mvn clean install -DskipTests，确保所有模块能正常构建
2. 在服务器上拉取最新代码到专门的构建目录
3. 执行mvn clean package -Pprod -DskipTests
4. 确认 target 目录下生成正确的 fat jar
5. 停止旧服务（如果用 systemd，执行systemctl stop user-service）
6. 备份旧 jar（cp user-service.jar user-service.jar.bak-20250115）
7. 将新 jar 拷贝到部署目录
8. 启动服务（systemctl start user-service）
9. 查看日志（journalctl -u user-service -f）确认启动成功
10. 用 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:$PATH

CI 里常见的做法就是在执行 Maven 构建前先 source 一个预置的环境配置文件，保证环境一致性。

9.3 结合 CI 的自动化部署思路

如果项目已经用 GitLab CI 或 Jenkins 做持续集成，Maven 的环节通常是这样的：

1. 代码提交触发流水线
2. 流水线拉取代码
3. 执行 Maven 构建（mvn clean package -DskipTests）
4. 将 jar 包归档到制品库
5. 触发部署任务，把 jar 推送到目标服务器
6. 重启服务

这个流程里 Maven 构建是核心环节，其他工具都在围着它转。流水线里 Maven 这块最值得注意的配置是：使用项目的 Maven Wrapper 或者固定 Maven 版本，不要依赖 Agent 自带的环境。另外要单独设置一个共享的本地仓库路径，避免每次构建全量拉依赖，这会极大拖慢流水线耗时。

我实际见过一个项目，因为没共享本地仓库，每次构建要拉 5 分钟依赖，整个流水线要 15 分钟。加了仓库缓存之后，依赖拉取降到 10 秒，流水线整体降到 3 分钟。这个优化性价比极高。

9.4 私有仓库（Nexus）在企业部署中的角色

前文提到过 Nexus，这里展开讲一下它和 Maven 配合的完整方案。Nexus 的核心功能是仓库管理，它有三种仓库类型：

• proxy 仓库：代理远程仓库（中央仓库、阿里云镜像），相当于一个缓存层
• hosted 仓库：托管团队自己发布的 jar 包，包括 release 和 snapshot
• group 仓库：把多个 proxy 和 hosted 聚合在一个地址下对外提供

企业里的标准配置是：开发人员的settings.xml里配一个<mirror>，将所有请求指向 Nexus 的 group 仓库，mirrorOf配置为*。Nexus 内部再代理阿里云镜像，这样整体链路变成了：本地 -> Nexus -> 阿里云 -> 中央仓库，多级缓存，速度极快。

团队发布 jar 包到 Nexus 时，pom.xml里的distributionManagement配置：

<distributionManagement> <repository> <id>releases</id> <name>Internal Releases</name> <url>http://nexus.internal/repository/maven-releases/</url> </repository> <snapshotRepository> <id>snapshots</id> <name>Internal Snapshots</name> <url>http://nexus.internal/repository/maven-snapshots/</url> </snapshotRepository> </distributionManagement>

对应的settings.xml里配置账号密码：

<servers> <server> <id>releases</id> <username>deploy</username> <password>password</password> </server> <server> <id>snapshots</id> <username>deploy</username> <password>password</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 这块彻底吃透。