很多刚接触 Java 开发的同学估计都经历过这么一幕照着网上的教程在 IDEA 里新建了一个 Spring Boot 项目然后眼睁睁看着右下角的小进度条转悠了十几二十分钟最后弹出一排红通通的报错Cannot resolve symbol SpringBootApplication或者Cannot resolve org.springframework.boot:spring-boot-starter-web:xxx。这时候十有八九问题就出在你手边的 Maven 身上。Maven 这个工具说简单也简单说复杂也能整出不少幺蛾子。它的本职工作是帮你管理项目依赖、执行构建流程、打包发布项目但配置不到位它也能让你一整天都在跟各种稀奇古怪的报错搏斗。这篇文章我就从零开始把 Maven 的下载安装、环境变量配置、本地仓库设置、阿里云镜像配置以及跟 IDEA 的联动配置全部捋一遍。里面会夹杂大量我这些年实际踩过的坑和总结的经验不是那种复制粘贴的官方文档式讲解希望能帮你一次性配好环境少走弯路。不管你是刚入门的 Java 新人还是已经写了几年代码但从来没搞明白 Maven 内部机制的老油条这篇内容都值得你花十分钟看完并收藏。1. 搞清楚 Maven 到底是干嘛的1.1 从一个 JDBC 驱动的小故事说起假设你现在要写一个最简单的 JDBC 连接 MySQL 的程序。在没有 Maven 的年代流程是这样的先去网上搜mysql-connector-java.jar下载下来丢到项目的lib目录里然后在 IDEA 里手动把这个 jar 包添加到Project Structure - Libraries。这还没完如果这个驱动还依赖了别的库实际上很多 jar 包都有传递依赖你还得把这个依赖的依赖也下载下来。一次两次还行等项目越来越大依赖的库越来越多你就会发现几个特别头疼的问题jar 包版本冲突A 库需要 commons-io 2.4B 库需要 commons-io 2.8你放哪个都会有一个不高兴还有 jar 包文件不知道什么时候就被谁覆盖了构建产物根本不可追溯更麻烦的是换一台电脑拉下代码光装这些依赖就得折腾半天。Maven 就是用来解决这个痛点的。你可以把它理解成一个品控严格的快递驿站你的项目只需要在pom.xml里写明我要用什么库、什么版本Maven 就会自动去配置好的远程仓库取货然后统一存放在本地仓库里再自动引入到你的项目构建路径中。全链路自动化版本统一管理还能保证可重复构建。1.2 Maven 解决的问题依赖管理、标准构建、项目信息Maven 的核心能力可以概括为三件事。第一是依赖管理。它通过pom.xmlProject Object Model项目对象模型描述项目需要的外部组件再通过坐标groupId、artifactId、version唯一定位每一个库。你说要mysql-connector-j:8.0.33它就去仓库里找这个坐标对应的文件绝对不会找错也不存在版本混用的问题。第二是标准化的项目构建流程。它定义了一套完备的生命周期比如clean清理、compile编译、test测试、package打包、install安装到本地仓库。同一段代码在谁的电脑上用 Maven 构建流程都是一样的从编译到打包全自动处理。第三是项目信息管理。Maven 不仅仅是构建工具它还能生成项目站点文档、管理依赖明细、生成依赖树等等。平时你可能感知不强但当你遇到依赖冲突、需要排查项目到底引入了哪些库的时候mvn dependency:tree这种命令能救你于水火。理解了 Maven 解决什么问题你再去看它的下载安装和配置就会自然很多——因为后面所有操作本质上都是为了让这个快递驿站的服务范围更大、取件速度更快、跟 IDEA 配合得更好。2. 环境准备与下载安装2.1 别急着下载 Maven先确认 JDK 版本很多教程上来就让你下载 Maven但我要先提醒一句Maven 本身是用 Java 写的它运行的前提是你电脑里已经装好了 JDK。不同版本的 Maven 对 JDK 版本有硬性要求。比如 Maven 3.9.x 要求 JDK 8 及以上如果你打算用 Spring Boot 3.x 那一套那 JDK 版本就得到 17 以上。下载前先用命令确认一下自己当前的环境java -version如果你看到类似openjdk version 17.0.8的输出那就没问题。如果java命令直接提示找不到那就先老老实实把 JDK 装上再继续这一步躲不掉的。另外一个隐藏要求是环境变量必须有JAVA_HOME。Maven 启动脚本会优先去找JAVA_HOME如果这个环境变量没有配置即使你在命令行里能运行javaMaven 也有可能报错。Windows 下配置JAVA_HOME的方式跟我下面要讲的 Maven 环境变量配置方式一模一样可以一起处理。2.2 官网下载 Maven 的正确姿势Maven 的官方下载地址是https://maven.apache.org/download.cgi。我见过太多人在搜索Maven 下载的时候点进了各种野鸡下载站结果下载下来一个捆绑了全家桶的安装包或者干脆下成源码包连怎么用都不知道。在官方网站上你会看到几个下载选项apache-maven-3.9.9-bin.zip这是我们要的二进制发行包apache-maven-3.9.9-src.zip这是源码包普通使用者不用管.tar.gzLinux/macOS 用的压缩格式Windows 下用 zip 即可下载时要注意白底官网页面上往往有一个Binary zip archive链接这个才是正确的。版本号就选当前最新的稳定版比如 3.9.x不要碰 alpha、beta 之类的版本图省事选稳定版最重要。下载完之后把压缩包解压到一个干净、无中文、无空格的路径下。Windows 用户我建议直接放到D:\dev\apache-maven-3.9.9这样级别的目录千万不要放在C:\Program Files下面因为后面可能有权限问题导致配置的本地仓库无法写入。macOS 用户就放到~/dev/apache-maven-3.9.9或者/usr/local/下面。2.3 环境变量配置与验证Windows macOS解压完成后需要让命令行认识mvn这个命令。我们需要配置两个环境变量。Windows 下的配置步骤右键此电脑 → 属性 → 高级系统设置 → 环境变量在系统变量区域点击新建变量名填MAVEN_HOME变量值填你的 Maven 解压路径比如D:\dev\apache-maven-3.9.9找到Path变量双击打开点击新建填入%MAVEN_HOME%\bin一路点击确定顺便把 JDK 的JAVA_HOME也检查一下没有的话一并配置好。配置完成后一定记得关掉当前所有命令行窗口重新打开否则新环境变量不会生效。macOS 下的配置步骤macOS 上如果你用的是 zsh现在基本都是就在~/.zshrc文件末尾追加几行export MAVEN_HOME~/dev/apache-maven-3.9.9 export PATH$MAVEN_HOME/bin:$PATH然后执行source ~/.zshrc让配置生效。验证配置是否成功新开一个命令行窗口输入mvn -v如果输出的内容里能看到类似Apache Maven 3.9.9、Maven home、Java version这几行信息恭喜Maven 已经装好了。这里插一句我当年的教训第一次配置完mvn -v提示mvn 不是内部或外部命令排查了半天发现是环境变量改了但没重新开终端。Windows 下配置完环境变量一定要把之前开着的命令行窗口全部关掉再重新打开一个新的这个习惯能帮你省下很多无谓的排查时间。3. 仓库配置本地仓库、中央仓库与阿里云镜像3.1 先弄明白本地仓库是什么Maven 的仓库分为三种本地仓库、中央仓库、远程仓库包括私服。本地仓库是 Maven 在你电脑本地的一个目录用来缓存所有从远程下载下来的依赖包。默认情况下这个目录在用户主目录下的.m2/repository也就是 Windows 的C:\Users\你的用户名\.m2\repositorymacOS/Linux 的~/.m2/repository。Maven 工作时会先在本地仓库里找依赖找到就直接用找不到才会去远程下载下载完再放到本地仓库。所以本地仓库其实就是你电脑上的缓存库项目越多、构建越频繁这个目录会越来越大。一个正经开发者电脑上这个目录动辄几个 GB 很常见。默认路径放在 C 盘其实有个隐患C 盘空间紧张或者遇到系统权限问题可能导致 Maven 下载依赖失败。所以我强烈建议把本地仓库路径改到一个专门的磁盘分区。3.2 修改 settings.xml本地仓库路径配置本地仓库路径的配置位置在 Maven 安装目录下的conf/settings.xml文件里。你可以直接改这个全局配置文件也可以把它复制一份到~/.m2/settings.xml后者是用户级配置优先级更高而且不会因为你重装 Maven 而丢失。打开settings.xml在文件开头不远的位置找到这段注释掉的配置!-- localRepository | The path to the local repository maven will use to store artifacts. --在你想要的位置添加一行localRepositoryD:\maven-repo/localRepositorymacOS 就写localRepository/Users/你的用户名/dev/maven-repo/localRepository注意这里填的是本地仓库的根目录不是.m2本身。配置好之后可以随便执行一个 Maven 命令验证如果某个依赖已经被下载过去新的本地仓库目录里检查一下是否有对应的文件夹。3.3 为什么需要阿里云镜像Maven 中央仓库官方地址在国外国内访问速度实在不敢恭维。一次构建要下载几十上百个 jar 包每个都从国外服务器上拉取等到黄花菜都凉了。这也是为什么网上的项目第一次构建时经常卡死在下载依赖这一步。解决办法就是配置镜像仓库。镜像是官方仓库的一个实时副本国内有阿里云、华为云、腾讯云等多个镜像源。其中阿里云镜像是目前国内使用最广泛、稳定性和更新速度都表现不错的一个。在settings.xml中找到mirrors节点添加如下配置mirrors mirror idaliyun/id nameAliyun Central Mirror/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror /mirrors这里解释一下关键参数url是镜像地址https://maven.aliyun.com/repository/public这个地址聚合了 Maven 中央仓库和 Jcenter 等几个常用源的内容日常使用基本够了。mirrorOf表示这个镜像拦截哪些仓库的请求central代表只要访问中央仓库就自动转发到这个镜像。如果想让所有远程仓库都走这个镜像可以写成mirrorOf*/mirrorOf但这种情况碰到私服配置时容易出问题我下面会细说。配置完镜像之后Maven 下载依赖时就不再直接请求中央仓库了而是转到阿里云速度提升非常明显第一次构建项目从等半小时还可能失败变成两三分钟搞定。3.4 多镜像仓库与私服 token 的配置策略很多人以为 mirror 配置只能写一个其实 Maven 支持配置多个镜像。比如你想优先用阿里云如果某些包阿里云没有再从其他源获取可以这样配置mirrors mirror idaliyun/id nameAliyun Central Mirror/name urlhttps://maven.aliyun.com/repository/public/url mirrorOf*,!my-repo/mirrorOf /mirror /mirrors这里用到了mirrorOf的通配符表达式。*,!my-repo的含义是拦截所有仓库的请求但排除my-repo这个仓库。这样你就可以在pom.xml里单独定义一个私有仓库my-repo让它直接走自己的地址不被镜像拦截。如果是公司内部私服或者你在 Gitea 之类的代码托管平台上托管了私有 Maven 仓库那就需要在settings.xml的servers节点里配置访问凭证。比如你只想让某个 token 只能访问指定的一个仓库可以在 Gitea 后台创建一个 fine-grained细粒度访问令牌只勾选目标仓库的 read:repository 权限然后把令牌用作 Maven 访问密码servers server idgitea-private-repo/id username你的用户名/username password这里是令牌字符串/password /server /servers注意这个id必须和pom.xml中repository或distributionManagement里声明的 id 保持一致。Gitea 创建细粒度 token 时仓库选择框里精确选中目标仓库即可这是从权限层面控制访问范围最干净的方式比用全局账号密码安全得多。不过我要提一句多个镜像的配置在实际使用时是有坑的。Maven 不会主动在多镜像之间做这个失败就自动切换另一个的故障转移它只会按照你声明的规则选择第一个匹配的镜像。所以如果担心阿里云偶尔不稳定更好的做法是在pom.xml的repositories里声明多套仓库利用 Maven 的仓库查找机制依次尝试不同来源。简单说镜像配置适合做替换仓库声明适合做兜底两者结合才能达到最优效果。4. IDEA 中集成与使用 Maven4.1 为什么不用 IDEA 自带的 MavenIDEA 是自带了一个 Maven 的新建项目的时候什么都不用配置就能跑起来。但我不建议你用自带的 Maven原因有三。第一IDEA 自带的 Maven 版本往往比当前最新版落后不少老项目对 Maven 版本有强约束版本不对会直接构建失败。第二你平时在命令行里敲mvn用的是自己下载配置的那个 Maven如果 IDEA 里用的是自带版本就会出现命令行能构建成功IDEA 里却失败的诡异现象。第三IDEA 自带 Maven 的配置文件使用逻辑不透明想自定义本地仓库路径和阿里的镜像时操作起来不如自己指定一个 settings.xml 来得清爽。所以我的建议是统一使用自己下载配置的那一套 Maven让 IDEA 指向同一份安装目录和同一份settings.xml。4.2 IDEA 中配置 Maven 的完整步骤打开 IDEA按Ctrl Alt S打开设置在搜索框里直接输入Maven或者依次展开Build, Execution, Deployment - Build Tools - Maven。在界面上你会看到几个关键配置项Maven home path填你自己的 Maven 安装路径比如D:\dev\apache-maven-3.9.9选择后 IDEA 会自动识别 Maven 版本。User settings file这里填你配置过的settings.xml路径。IDEA 默认会读取~/.m2/settings.xml如果你改的是全局配置也可以手动指定 Maven 安装目录下的conf/settings.xml。选好后如果右侧有Override复选框记得勾上这样才能保证 IDEA 严格使用你指定的配置文件。Local repositoryIDEA 会根据 settings.xml 自动解析出本地仓库路径。如果没有自动带出来就手动填一下。配置完之后点击右侧的Maven工具窗口IDEA 右侧边栏的 M 图标在窗口顶部的工具栏里找到那个刷新图标的按钮点击触发一次重新加载。IDEA 会把当前项目重新解析一遍pom.xml并开始下载依赖。另外要说一下新版 IDEA 里 Maven 设置的入口和旧版略有差别但核心的三个路径位置基本一致。如果你用的是社区版 IDEA也不用担心Maven 相关功能在社区版里一个不差完全够用。4.3 创建 Maven 项目并验证依赖是否安装成功配置好 Maven 之后我们新建一个项目来验证整个链路是否通畅。打开 IDEA选择File - New - Project。左侧选MavenProject SDK 选你本地的 JDK勾选Create from archetype并选择maven-archetype-quickstart这是最基础的 Java 项目骨架。如果你要建 Spring Boot 项目更好的做法是先到start.spring.io下载项目压缩包然后在 IDEA 里直接导入因为官方生成的模板已经把依赖写全了。项目创建后IDEA 会自动读取根目录下的pom.xml。你只需要往里面加两个依赖试试dependencies dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency /dependencies保存pom.xml后右侧 Maven 窗口会自动刷新。你观察一下状态栏如果依赖能顺利下载问题就不大。如果下载过程中报错重点检查settings.xml里的本地仓库路径和镜像配置是否正确。依赖下载完成后在 IDEA 的Project Structure - Libraries里就能看到对应的 jar 包。4.4 常用 Maven 命令与生命周期配置好 IDEA 里的 Maven 以后你会频繁用到右侧 Maven 工具窗口里的 Lifecycle 列表。这个列表对应 Maven 的标准生命周期阶段从上到下依次是clean清理 target 目录里的编译产物validate校验项目信息是否正确compile编译主代码test运行测试代码这里会先编译主代码和测试代码package打包会生成 jar/war 文件到 target 目录并在此之前完成测试verify对集成测试结果进行进一步检查install把打好的包安装到本地仓库别人本机其他项目就可以引用了双击对应条目就能在 IDEA 里直接执行。如果你在 IDEA 里打包部署 Spring Boot 项目package之后会在target目录下生成可执行的 jar。但要注意Spring Boot 的重新打包要求spring-boot-maven-plugin在pom.xml里配置如果没有这个插件打出来的 jar 是不能直接java -jar运行的这又是另一个常见的坑。命令行下最常用的组合是mvn clean install如果 Xcode 习惯了的话也可以加参数跳过测试mvn clean install -DskipTests。IDEA 的 Maven 工具窗口和命令行操作是等效的两者任选其一即可。5. 常见问题与排查技巧实录5.1 依赖下载失败的几种情况与处理思路Maven 使用中最高频的问题就是依赖下载失败或者根本无法解析。典型报错长这样Cannot resolve com.mysql:mysql-connector-j:8.0.33或者Could not transfer artifact ... Connection timed out遇到这类问题我的排查顺序是固定的第一确认settings.xml里的本地仓库路径和镜像配置是否生效。很多人改了全局配置但 IDEA 里却还在用默认的~/.m2/settings.xml导致配置不生效。第二检查网络连通性。手动在浏览器里访问一下镜像地址比如https://maven.aliyun.com/repository/public如果打不开那多半是网络问题。第三确认 jar 包是否真的存在。去远程仓库页面上搜索mysql-connector-j的版本列表看你要的版本号是否存在。有些第三方库的新版本发布会有延迟中央仓库和镜像之间还没同步。第四强制更新快照和缓存。有时候本地仓库里的.lastUpdated文件记录了失败状态导致 Maven 不再尝试重新下载。在 IDEA 里点 Maven 工具窗口的Reload All Maven Projects或者在命令行执行mvn clean install -U这个-U参数是强制检查远程仓库的更新和快照版本对解决缓存类问题很有效。第五如果还是不行干脆把本地仓库里对应目录整个删掉重新下载。这招简单粗暴但经常能解决一些莫名其妙的缓存损坏问题。5.2 版本冲突与依赖树的排查技巧项目依赖多了以后很容易出现同一个库的多个版本被不同的依赖间接引用了。典型的报错是NoSuchMethodError或者ClassNotFoundException明明代码里没出错运行时就报错多半就是版本冲突导致的。处理版本冲突我一般用 Maven 的依赖树命令mvn dependency:tree -Dverbose在 IDEA 的 Terminal 窗口或者右侧 Maven 工具窗口里都可以执行。依赖树会把你项目里所有依赖的层级关系展示出来。找到可疑的库看看哪个坐标引用的是旧版本然后在你自己的pom.xml里用exclusions排除低版本传递依赖或者直接显式声明一个更高版本。这里有个小技巧mvn dependency:tree输出的内容可能特别长可以先输出到文件里再慢慢看mvn dependency:tree -Dverbose dep.txt然后用文本编辑器打开慢慢查。5.3 其他高频问题速查除了上面两大问题我还列了一些平时群里被问到最多的情况整理成一个速查表问题现象常见原因解决方案IDEA 里 Maven 一直转圈下载没进度镜像配置没生效 / 访问中央仓库超时配置阿里云镜像并重新 Reloadmvn -v 提示找不到命令环境变量未配置或未重新开终端检查 Path 配置重新打开命令行窗口本地仓库越来越大C 盘爆了默认仓库在 C 盘用户目录下修改 settings.xml 指向其他盘打包后 java -jar 运行报 no main manifest attributeSpring Boot 插件缺失在 pom.xml 添加 spring-boot-maven-plugin命令行 mvn 编译成功IDEA 里失败IDEA 用的还是自带 Maven在 IDEA 设置里指定同一份 Maven 路径settings.xml 改了没反应修改的是全局配置IDEA 用了用户配置勾选 User settings file 的 Override并指向正确的文件Maven 下载依赖时使用 http 被阻断中央仓库只允许 https 请求镜像地址务必使用 https5.4 几个独家的实操经验最后分享几个文档里不太会写的经验。关于~/.m2/repository的权限问题Windows 用户如果本地仓库在 C 盘用户目录下遇到依赖下载失败、日志显示 Permission Denied多半是用户目录权限不够。改到其他盘的独立目录可以彻底规避这个问题。关于 IDEA 中 Maven 自动导入的选项在Settings - Build, Execution, Deployment - Build Tools - Maven - Importing里有一项Automatically import如果你没有勾选那么每次修改pom.xml之后都要手动刷新。建议勾上Import Maven projects automatically省得天天手动点 Reload。关于 Maven 的 JDK 编译版本如果你在 IDEA 里编译代码没问题但mvn compile时报invalid target release错误说明 Maven 使用的JAVA_HOME和 IDEA 设置的 JDK 不一致。在 IDEA 的设置里找到Java Compiler把 Target bytecode version 和项目的 SDK 统一一下再检查一下环境变量里的JAVA_HOME是否指向了正确版本的 JDK。这种问题在电脑上装了多个 JDK 版本的时候特别常见。关于 Maven 命令行输出中文乱码Windows 下执行mvn命令时如果日志里的中文全部变成了问号或者乱码一般是因为命令行窗口的编码和系统默认编码不一致。可以在MAVEN_OPTS环境变量里加上-Dfile.encodingUTF-8或者配置 IDEA 的 Terminal 编码为 UTF-8 来解决。6. 收尾写在最后的一点建议我这几年配过的开发环境没有五十台也有三十台了Maven 的坑踩来踩去其实核心就那么几个路径带中文、环境变量没刷新生效、settings.xml 改的是全局但 IDEA 读的是用户配置、网络问题导致下载失败。只要你把这几条提前避掉了Maven 这个工具还是相当省心的。我个人现在的新机器配置流程固定了先装 JDK再解压 Maven改本地仓库到 D 盘把阿里云镜像写进 settings.xml最后在 IDEA 里统一指定 Maven home 和配置文件全套下来不到十分钟。建议你也把自己的这套配置流程固化下来以后换电脑或者帮同事排查环境问题的时候照着流程走一遍能省下大量时间。如果你看完这篇文章配好了 Maven记得实际建一个项目、加几个依赖跑一遍别配完就万事大吉。只有真实跑过依赖下载、编译、打包这条完整链路你才算真正把环境配好了。
很多刚接触 Java 开发的同学估计都经历过这么一幕照着网上的教程在 IDEA 里新建了一个 Spring Boot 项目然后眼睁睁看着右下角的小进度条转悠了十几二十分钟最后弹出一排红通通的报错Cannot resolve symbol SpringBootApplication或者Cannot resolve org.springframework.boot:spring-boot-starter-web:xxx。这时候十有八九问题就出在你手边的 Maven 身上。Maven 这个工具说简单也简单说复杂也能整出不少幺蛾子。它的本职工作是帮你管理项目依赖、执行构建流程、打包发布项目但配置不到位它也能让你一整天都在跟各种稀奇古怪的报错搏斗。这篇文章我就从零开始把 Maven 的下载安装、环境变量配置、本地仓库设置、阿里云镜像配置以及跟 IDEA 的联动配置全部捋一遍。里面会夹杂大量我这些年实际踩过的坑和总结的经验不是那种复制粘贴的官方文档式讲解希望能帮你一次性配好环境少走弯路。不管你是刚入门的 Java 新人还是已经写了几年代码但从来没搞明白 Maven 内部机制的老油条这篇内容都值得你花十分钟看完并收藏。1. 搞清楚 Maven 到底是干嘛的1.1 从一个 JDBC 驱动的小故事说起假设你现在要写一个最简单的 JDBC 连接 MySQL 的程序。在没有 Maven 的年代流程是这样的先去网上搜mysql-connector-java.jar下载下来丢到项目的lib目录里然后在 IDEA 里手动把这个 jar 包添加到Project Structure - Libraries。这还没完如果这个驱动还依赖了别的库实际上很多 jar 包都有传递依赖你还得把这个依赖的依赖也下载下来。一次两次还行等项目越来越大依赖的库越来越多你就会发现几个特别头疼的问题jar 包版本冲突A 库需要 commons-io 2.4B 库需要 commons-io 2.8你放哪个都会有一个不高兴还有 jar 包文件不知道什么时候就被谁覆盖了构建产物根本不可追溯更麻烦的是换一台电脑拉下代码光装这些依赖就得折腾半天。Maven 就是用来解决这个痛点的。你可以把它理解成一个品控严格的快递驿站你的项目只需要在pom.xml里写明我要用什么库、什么版本Maven 就会自动去配置好的远程仓库取货然后统一存放在本地仓库里再自动引入到你的项目构建路径中。全链路自动化版本统一管理还能保证可重复构建。1.2 Maven 解决的问题依赖管理、标准构建、项目信息Maven 的核心能力可以概括为三件事。第一是依赖管理。它通过pom.xmlProject Object Model项目对象模型描述项目需要的外部组件再通过坐标groupId、artifactId、version唯一定位每一个库。你说要mysql-connector-j:8.0.33它就去仓库里找这个坐标对应的文件绝对不会找错也不存在版本混用的问题。第二是标准化的项目构建流程。它定义了一套完备的生命周期比如clean清理、compile编译、test测试、package打包、install安装到本地仓库。同一段代码在谁的电脑上用 Maven 构建流程都是一样的从编译到打包全自动处理。第三是项目信息管理。Maven 不仅仅是构建工具它还能生成项目站点文档、管理依赖明细、生成依赖树等等。平时你可能感知不强但当你遇到依赖冲突、需要排查项目到底引入了哪些库的时候mvn dependency:tree这种命令能救你于水火。理解了 Maven 解决什么问题你再去看它的下载安装和配置就会自然很多——因为后面所有操作本质上都是为了让这个快递驿站的服务范围更大、取件速度更快、跟 IDEA 配合得更好。2. 环境准备与下载安装2.1 别急着下载 Maven先确认 JDK 版本很多教程上来就让你下载 Maven但我要先提醒一句Maven 本身是用 Java 写的它运行的前提是你电脑里已经装好了 JDK。不同版本的 Maven 对 JDK 版本有硬性要求。比如 Maven 3.9.x 要求 JDK 8 及以上如果你打算用 Spring Boot 3.x 那一套那 JDK 版本就得到 17 以上。下载前先用命令确认一下自己当前的环境java -version如果你看到类似openjdk version 17.0.8的输出那就没问题。如果java命令直接提示找不到那就先老老实实把 JDK 装上再继续这一步躲不掉的。另外一个隐藏要求是环境变量必须有JAVA_HOME。Maven 启动脚本会优先去找JAVA_HOME如果这个环境变量没有配置即使你在命令行里能运行javaMaven 也有可能报错。Windows 下配置JAVA_HOME的方式跟我下面要讲的 Maven 环境变量配置方式一模一样可以一起处理。2.2 官网下载 Maven 的正确姿势Maven 的官方下载地址是https://maven.apache.org/download.cgi。我见过太多人在搜索Maven 下载的时候点进了各种野鸡下载站结果下载下来一个捆绑了全家桶的安装包或者干脆下成源码包连怎么用都不知道。在官方网站上你会看到几个下载选项apache-maven-3.9.9-bin.zip这是我们要的二进制发行包apache-maven-3.9.9-src.zip这是源码包普通使用者不用管.tar.gzLinux/macOS 用的压缩格式Windows 下用 zip 即可下载时要注意白底官网页面上往往有一个Binary zip archive链接这个才是正确的。版本号就选当前最新的稳定版比如 3.9.x不要碰 alpha、beta 之类的版本图省事选稳定版最重要。下载完之后把压缩包解压到一个干净、无中文、无空格的路径下。Windows 用户我建议直接放到D:\dev\apache-maven-3.9.9这样级别的目录千万不要放在C:\Program Files下面因为后面可能有权限问题导致配置的本地仓库无法写入。macOS 用户就放到~/dev/apache-maven-3.9.9或者/usr/local/下面。2.3 环境变量配置与验证Windows macOS解压完成后需要让命令行认识mvn这个命令。我们需要配置两个环境变量。Windows 下的配置步骤右键此电脑 → 属性 → 高级系统设置 → 环境变量在系统变量区域点击新建变量名填MAVEN_HOME变量值填你的 Maven 解压路径比如D:\dev\apache-maven-3.9.9找到Path变量双击打开点击新建填入%MAVEN_HOME%\bin一路点击确定顺便把 JDK 的JAVA_HOME也检查一下没有的话一并配置好。配置完成后一定记得关掉当前所有命令行窗口重新打开否则新环境变量不会生效。macOS 下的配置步骤macOS 上如果你用的是 zsh现在基本都是就在~/.zshrc文件末尾追加几行export MAVEN_HOME~/dev/apache-maven-3.9.9 export PATH$MAVEN_HOME/bin:$PATH然后执行source ~/.zshrc让配置生效。验证配置是否成功新开一个命令行窗口输入mvn -v如果输出的内容里能看到类似Apache Maven 3.9.9、Maven home、Java version这几行信息恭喜Maven 已经装好了。这里插一句我当年的教训第一次配置完mvn -v提示mvn 不是内部或外部命令排查了半天发现是环境变量改了但没重新开终端。Windows 下配置完环境变量一定要把之前开着的命令行窗口全部关掉再重新打开一个新的这个习惯能帮你省下很多无谓的排查时间。3. 仓库配置本地仓库、中央仓库与阿里云镜像3.1 先弄明白本地仓库是什么Maven 的仓库分为三种本地仓库、中央仓库、远程仓库包括私服。本地仓库是 Maven 在你电脑本地的一个目录用来缓存所有从远程下载下来的依赖包。默认情况下这个目录在用户主目录下的.m2/repository也就是 Windows 的C:\Users\你的用户名\.m2\repositorymacOS/Linux 的~/.m2/repository。Maven 工作时会先在本地仓库里找依赖找到就直接用找不到才会去远程下载下载完再放到本地仓库。所以本地仓库其实就是你电脑上的缓存库项目越多、构建越频繁这个目录会越来越大。一个正经开发者电脑上这个目录动辄几个 GB 很常见。默认路径放在 C 盘其实有个隐患C 盘空间紧张或者遇到系统权限问题可能导致 Maven 下载依赖失败。所以我强烈建议把本地仓库路径改到一个专门的磁盘分区。3.2 修改 settings.xml本地仓库路径配置本地仓库路径的配置位置在 Maven 安装目录下的conf/settings.xml文件里。你可以直接改这个全局配置文件也可以把它复制一份到~/.m2/settings.xml后者是用户级配置优先级更高而且不会因为你重装 Maven 而丢失。打开settings.xml在文件开头不远的位置找到这段注释掉的配置!-- localRepository | The path to the local repository maven will use to store artifacts. --在你想要的位置添加一行localRepositoryD:\maven-repo/localRepositorymacOS 就写localRepository/Users/你的用户名/dev/maven-repo/localRepository注意这里填的是本地仓库的根目录不是.m2本身。配置好之后可以随便执行一个 Maven 命令验证如果某个依赖已经被下载过去新的本地仓库目录里检查一下是否有对应的文件夹。3.3 为什么需要阿里云镜像Maven 中央仓库官方地址在国外国内访问速度实在不敢恭维。一次构建要下载几十上百个 jar 包每个都从国外服务器上拉取等到黄花菜都凉了。这也是为什么网上的项目第一次构建时经常卡死在下载依赖这一步。解决办法就是配置镜像仓库。镜像是官方仓库的一个实时副本国内有阿里云、华为云、腾讯云等多个镜像源。其中阿里云镜像是目前国内使用最广泛、稳定性和更新速度都表现不错的一个。在settings.xml中找到mirrors节点添加如下配置mirrors mirror idaliyun/id nameAliyun Central Mirror/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror /mirrors这里解释一下关键参数url是镜像地址https://maven.aliyun.com/repository/public这个地址聚合了 Maven 中央仓库和 Jcenter 等几个常用源的内容日常使用基本够了。mirrorOf表示这个镜像拦截哪些仓库的请求central代表只要访问中央仓库就自动转发到这个镜像。如果想让所有远程仓库都走这个镜像可以写成mirrorOf*/mirrorOf但这种情况碰到私服配置时容易出问题我下面会细说。配置完镜像之后Maven 下载依赖时就不再直接请求中央仓库了而是转到阿里云速度提升非常明显第一次构建项目从等半小时还可能失败变成两三分钟搞定。3.4 多镜像仓库与私服 token 的配置策略很多人以为 mirror 配置只能写一个其实 Maven 支持配置多个镜像。比如你想优先用阿里云如果某些包阿里云没有再从其他源获取可以这样配置mirrors mirror idaliyun/id nameAliyun Central Mirror/name urlhttps://maven.aliyun.com/repository/public/url mirrorOf*,!my-repo/mirrorOf /mirror /mirrors这里用到了mirrorOf的通配符表达式。*,!my-repo的含义是拦截所有仓库的请求但排除my-repo这个仓库。这样你就可以在pom.xml里单独定义一个私有仓库my-repo让它直接走自己的地址不被镜像拦截。如果是公司内部私服或者你在 Gitea 之类的代码托管平台上托管了私有 Maven 仓库那就需要在settings.xml的servers节点里配置访问凭证。比如你只想让某个 token 只能访问指定的一个仓库可以在 Gitea 后台创建一个 fine-grained细粒度访问令牌只勾选目标仓库的 read:repository 权限然后把令牌用作 Maven 访问密码servers server idgitea-private-repo/id username你的用户名/username password这里是令牌字符串/password /server /servers注意这个id必须和pom.xml中repository或distributionManagement里声明的 id 保持一致。Gitea 创建细粒度 token 时仓库选择框里精确选中目标仓库即可这是从权限层面控制访问范围最干净的方式比用全局账号密码安全得多。不过我要提一句多个镜像的配置在实际使用时是有坑的。Maven 不会主动在多镜像之间做这个失败就自动切换另一个的故障转移它只会按照你声明的规则选择第一个匹配的镜像。所以如果担心阿里云偶尔不稳定更好的做法是在pom.xml的repositories里声明多套仓库利用 Maven 的仓库查找机制依次尝试不同来源。简单说镜像配置适合做替换仓库声明适合做兜底两者结合才能达到最优效果。4. IDEA 中集成与使用 Maven4.1 为什么不用 IDEA 自带的 MavenIDEA 是自带了一个 Maven 的新建项目的时候什么都不用配置就能跑起来。但我不建议你用自带的 Maven原因有三。第一IDEA 自带的 Maven 版本往往比当前最新版落后不少老项目对 Maven 版本有强约束版本不对会直接构建失败。第二你平时在命令行里敲mvn用的是自己下载配置的那个 Maven如果 IDEA 里用的是自带版本就会出现命令行能构建成功IDEA 里却失败的诡异现象。第三IDEA 自带 Maven 的配置文件使用逻辑不透明想自定义本地仓库路径和阿里的镜像时操作起来不如自己指定一个 settings.xml 来得清爽。所以我的建议是统一使用自己下载配置的那一套 Maven让 IDEA 指向同一份安装目录和同一份settings.xml。4.2 IDEA 中配置 Maven 的完整步骤打开 IDEA按Ctrl Alt S打开设置在搜索框里直接输入Maven或者依次展开Build, Execution, Deployment - Build Tools - Maven。在界面上你会看到几个关键配置项Maven home path填你自己的 Maven 安装路径比如D:\dev\apache-maven-3.9.9选择后 IDEA 会自动识别 Maven 版本。User settings file这里填你配置过的settings.xml路径。IDEA 默认会读取~/.m2/settings.xml如果你改的是全局配置也可以手动指定 Maven 安装目录下的conf/settings.xml。选好后如果右侧有Override复选框记得勾上这样才能保证 IDEA 严格使用你指定的配置文件。Local repositoryIDEA 会根据 settings.xml 自动解析出本地仓库路径。如果没有自动带出来就手动填一下。配置完之后点击右侧的Maven工具窗口IDEA 右侧边栏的 M 图标在窗口顶部的工具栏里找到那个刷新图标的按钮点击触发一次重新加载。IDEA 会把当前项目重新解析一遍pom.xml并开始下载依赖。另外要说一下新版 IDEA 里 Maven 设置的入口和旧版略有差别但核心的三个路径位置基本一致。如果你用的是社区版 IDEA也不用担心Maven 相关功能在社区版里一个不差完全够用。4.3 创建 Maven 项目并验证依赖是否安装成功配置好 Maven 之后我们新建一个项目来验证整个链路是否通畅。打开 IDEA选择File - New - Project。左侧选MavenProject SDK 选你本地的 JDK勾选Create from archetype并选择maven-archetype-quickstart这是最基础的 Java 项目骨架。如果你要建 Spring Boot 项目更好的做法是先到start.spring.io下载项目压缩包然后在 IDEA 里直接导入因为官方生成的模板已经把依赖写全了。项目创建后IDEA 会自动读取根目录下的pom.xml。你只需要往里面加两个依赖试试dependencies dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId version8.0.33/version /dependency /dependencies保存pom.xml后右侧 Maven 窗口会自动刷新。你观察一下状态栏如果依赖能顺利下载问题就不大。如果下载过程中报错重点检查settings.xml里的本地仓库路径和镜像配置是否正确。依赖下载完成后在 IDEA 的Project Structure - Libraries里就能看到对应的 jar 包。4.4 常用 Maven 命令与生命周期配置好 IDEA 里的 Maven 以后你会频繁用到右侧 Maven 工具窗口里的 Lifecycle 列表。这个列表对应 Maven 的标准生命周期阶段从上到下依次是clean清理 target 目录里的编译产物validate校验项目信息是否正确compile编译主代码test运行测试代码这里会先编译主代码和测试代码package打包会生成 jar/war 文件到 target 目录并在此之前完成测试verify对集成测试结果进行进一步检查install把打好的包安装到本地仓库别人本机其他项目就可以引用了双击对应条目就能在 IDEA 里直接执行。如果你在 IDEA 里打包部署 Spring Boot 项目package之后会在target目录下生成可执行的 jar。但要注意Spring Boot 的重新打包要求spring-boot-maven-plugin在pom.xml里配置如果没有这个插件打出来的 jar 是不能直接java -jar运行的这又是另一个常见的坑。命令行下最常用的组合是mvn clean install如果 Xcode 习惯了的话也可以加参数跳过测试mvn clean install -DskipTests。IDEA 的 Maven 工具窗口和命令行操作是等效的两者任选其一即可。5. 常见问题与排查技巧实录5.1 依赖下载失败的几种情况与处理思路Maven 使用中最高频的问题就是依赖下载失败或者根本无法解析。典型报错长这样Cannot resolve com.mysql:mysql-connector-j:8.0.33或者Could not transfer artifact ... Connection timed out遇到这类问题我的排查顺序是固定的第一确认settings.xml里的本地仓库路径和镜像配置是否生效。很多人改了全局配置但 IDEA 里却还在用默认的~/.m2/settings.xml导致配置不生效。第二检查网络连通性。手动在浏览器里访问一下镜像地址比如https://maven.aliyun.com/repository/public如果打不开那多半是网络问题。第三确认 jar 包是否真的存在。去远程仓库页面上搜索mysql-connector-j的版本列表看你要的版本号是否存在。有些第三方库的新版本发布会有延迟中央仓库和镜像之间还没同步。第四强制更新快照和缓存。有时候本地仓库里的.lastUpdated文件记录了失败状态导致 Maven 不再尝试重新下载。在 IDEA 里点 Maven 工具窗口的Reload All Maven Projects或者在命令行执行mvn clean install -U这个-U参数是强制检查远程仓库的更新和快照版本对解决缓存类问题很有效。第五如果还是不行干脆把本地仓库里对应目录整个删掉重新下载。这招简单粗暴但经常能解决一些莫名其妙的缓存损坏问题。5.2 版本冲突与依赖树的排查技巧项目依赖多了以后很容易出现同一个库的多个版本被不同的依赖间接引用了。典型的报错是NoSuchMethodError或者ClassNotFoundException明明代码里没出错运行时就报错多半就是版本冲突导致的。处理版本冲突我一般用 Maven 的依赖树命令mvn dependency:tree -Dverbose在 IDEA 的 Terminal 窗口或者右侧 Maven 工具窗口里都可以执行。依赖树会把你项目里所有依赖的层级关系展示出来。找到可疑的库看看哪个坐标引用的是旧版本然后在你自己的pom.xml里用exclusions排除低版本传递依赖或者直接显式声明一个更高版本。这里有个小技巧mvn dependency:tree输出的内容可能特别长可以先输出到文件里再慢慢看mvn dependency:tree -Dverbose dep.txt然后用文本编辑器打开慢慢查。5.3 其他高频问题速查除了上面两大问题我还列了一些平时群里被问到最多的情况整理成一个速查表问题现象常见原因解决方案IDEA 里 Maven 一直转圈下载没进度镜像配置没生效 / 访问中央仓库超时配置阿里云镜像并重新 Reloadmvn -v 提示找不到命令环境变量未配置或未重新开终端检查 Path 配置重新打开命令行窗口本地仓库越来越大C 盘爆了默认仓库在 C 盘用户目录下修改 settings.xml 指向其他盘打包后 java -jar 运行报 no main manifest attributeSpring Boot 插件缺失在 pom.xml 添加 spring-boot-maven-plugin命令行 mvn 编译成功IDEA 里失败IDEA 用的还是自带 Maven在 IDEA 设置里指定同一份 Maven 路径settings.xml 改了没反应修改的是全局配置IDEA 用了用户配置勾选 User settings file 的 Override并指向正确的文件Maven 下载依赖时使用 http 被阻断中央仓库只允许 https 请求镜像地址务必使用 https5.4 几个独家的实操经验最后分享几个文档里不太会写的经验。关于~/.m2/repository的权限问题Windows 用户如果本地仓库在 C 盘用户目录下遇到依赖下载失败、日志显示 Permission Denied多半是用户目录权限不够。改到其他盘的独立目录可以彻底规避这个问题。关于 IDEA 中 Maven 自动导入的选项在Settings - Build, Execution, Deployment - Build Tools - Maven - Importing里有一项Automatically import如果你没有勾选那么每次修改pom.xml之后都要手动刷新。建议勾上Import Maven projects automatically省得天天手动点 Reload。关于 Maven 的 JDK 编译版本如果你在 IDEA 里编译代码没问题但mvn compile时报invalid target release错误说明 Maven 使用的JAVA_HOME和 IDEA 设置的 JDK 不一致。在 IDEA 的设置里找到Java Compiler把 Target bytecode version 和项目的 SDK 统一一下再检查一下环境变量里的JAVA_HOME是否指向了正确版本的 JDK。这种问题在电脑上装了多个 JDK 版本的时候特别常见。关于 Maven 命令行输出中文乱码Windows 下执行mvn命令时如果日志里的中文全部变成了问号或者乱码一般是因为命令行窗口的编码和系统默认编码不一致。可以在MAVEN_OPTS环境变量里加上-Dfile.encodingUTF-8或者配置 IDEA 的 Terminal 编码为 UTF-8 来解决。6. 收尾写在最后的一点建议我这几年配过的开发环境没有五十台也有三十台了Maven 的坑踩来踩去其实核心就那么几个路径带中文、环境变量没刷新生效、settings.xml 改的是全局但 IDEA 读的是用户配置、网络问题导致下载失败。只要你把这几条提前避掉了Maven 这个工具还是相当省心的。我个人现在的新机器配置流程固定了先装 JDK再解压 Maven改本地仓库到 D 盘把阿里云镜像写进 settings.xml最后在 IDEA 里统一指定 Maven home 和配置文件全套下来不到十分钟。建议你也把自己的这套配置流程固化下来以后换电脑或者帮同事排查环境问题的时候照着流程走一遍能省下大量时间。如果你看完这篇文章配好了 Maven记得实际建一个项目、加几个依赖跑一遍别配完就万事大吉。只有真实跑过依赖下载、编译、打包这条完整链路你才算真正把环境配好了。
