Maven安装与配置实战：JDK、环境变量、镜像与本地仓库

1. 先把为什么要装 Maven这件事想明白我见过太多人装 Maven 的过程搜一篇教程照着复制两行环境变量敲个mvn -v看到版本号刷出来截图保存收工。然后一周后跑构建报了个看不懂的错才发现自己压根不知道刚才装的那个东西在干什么。这套流程本身没错但漏掉了一环——你得先知道 Maven 在你的工程里扮演什么角色才能判断哪些配置是必须的、哪些是老教程里的历史包袱。Maven 是 Java 生态里最主流的项目构建与依赖管理工具。它替你做三件事把散落在各处的第三方 jar 按声明自动拉下来、按一套标准目录结构编译打包、把一长串构建命令收敛成mvn clean package这样一句话。这三件事听起来平平无奇但它们解决的痛点是实打实的。这篇内容面向的是刚上手 Java 项目、或者长期用 IDE 图形界面点按钮、想搞清楚命令行构建到底怎么回事的朋友。装完之后你会得到什么一个能在任意目录下直接调用的mvn命令、一套按你的网络环境调好的仓库配置、以及一份遇到常见报错时能自己定位的排查思路。不需要你已经有成熟的 Java 项目一个空目录就够了。1.1 手动往 lib 目录里丢 jar 包到底卡在哪一步先讲个我早年的真实教训。那时候接了个小项目需要用到几个 JSON 处理、日志、数据库连接的库。我的做法是从各处下载 jar 文件一股脑拖进工程目录下新建的lib文件夹然后在 IDE 里一个个 Add to Build Path。头两周一切正常。第三周出问题了。日志库升级了一个大版本新版本内部依赖了另一个工具包那个工具包又依赖了一个特定版本的字节码处理库。我把新日志库的 jar 换进去编译通过启动就抛NoSuchMethodError。这个错误的本质是我换上去的 jar 和原来工程里残留的旧版字节码处理库版本对不上。而我手里根本没有一份文档告诉我这个日志库的 2.x 版本需要字节码处理库的 1.4 以上。这就是手动管理 jar 的死穴——依赖是有传递性的而你的人脑不擅长记录传递关系。A 依赖 BB 依赖 C 和 DD 又对 C 的版本有下限要求这种关系链叠到三层以上靠人肉维护必然出错。Maven 的出现就是把这个关系交给机器去算你在pom.xml里只写你直接用的那几个库剩下的传递依赖它自己解析版本冲突它自己按最近优先的规则裁决还会在你要求时吐出一棵完整的依赖树让你核对。所以装 Maven 之前先建立一个认知它不是个可有可无的辅助工具而是 Java 工程的事实标准基础设施。你现在电脑上那些开源项目、公司里那些老系统九成以上都靠它或者它的同类工具在跑构建。1.2 Maven 干活的三个环节对应你要配的三样东西Maven 的运行逻辑可以拆成一条很清晰的链子理解这条链子后面所有配置项你都能对上号。第一个环节是找包。Maven 需要某个依赖时先看本地仓库里有没有没有就去远程仓库下载下载完缓存在本地。这对应你要配的两样东西本地仓库的位置默认在用户目录下的.m2/repository、远程仓库的地址默认是中央仓库网络不通畅时要换成能访问的镜像。第二个环节是算版本。同一个库被不同依赖引入了多个版本时Maven 按一套既定规则选出最终生效的那个。这一环不需要你配什么但需要你知道它的存在否则将来遇到明明我写的 2.0 版本怎么实际加载的是 1.8会一头雾水。第三个环节是跑生命周期。clean、compile、test、package、install这些阶段是有顺序的你敲mvn install它会自动把前面的阶段全跑一遍。这一环的关键是插件——编译用编译插件、打包用打包插件、跑测试用测试插件这些插件的版本决定了你的代码能不能用上新 JDK 的语法特性。把这三环记住后面看到settings.xml里那一堆标签你就不会懵localRepository管第一环的缓存位置mirrors管第一环的下载通道profiles里配的 JDK 版本管第三环的编译行为。1.3 装 Maven 之前JDK 这件事必须先落地Maven 本身是个 Java 程序它自己跑起来需要 JVM。所以顺序永远是先装 JDK配好JAVA_HOME再装 Maven。这里有两个容易翻车的细节我提前说清楚。第一JAVA_HOME要指向 JDK 的根目录不是bin目录。很多教程写得不清楚导致有人配成了C:\Program Files\Java\jdk-17\bin结果 Maven 启动时报找不到 Java 运行时。正确的值形如C:\Program Files\Java\jdk-17Maven 会自己在后面拼上\bin\java.exe。第二Maven 3.9.x 系列最低要求 JDK 8。如果你电脑上同时装了多个 JDK比如项目需要 8、自己学习想用 17那就更要注意Maven 用的是JAVA_HOME指向的那个 JDK而不是你PATH里排在前面的那个。这是个非常常见的错位——你在命令行敲java -version显示 17mvn -v却告诉你 Java version: 1.8很多人第一反应是 Maven 装坏了其实是两个变量指向了不同的 JDK。提示在动手装 Maven 之前先开个新的终端窗口执行java -version和echo %JAVA_HOME%Linux/macOS 用echo $JAVA_HOME两边的版本对得上再往下走。这一步花三十秒能省掉后面半小时的排查。2. 挑安装包版本号、包类型与校验下载环节看似最简单但选错包类型或者选错版本后面会连带出一串麻烦。我把挑选时需要判断的几个点拆开讲。2.1 版本号三段数字各自代表什么Maven 的版本号形如3.9.6三段数字的含义大致是第一段是大版本第二段是功能版本第三段是修正版本。选版本的时候遵循两条经验法则。一条是大版本跟随主流。目前主流稳定的是 3.x 系列这个系列的生态最成熟各类插件兼容性最好。如果你在某处看到 4.x 的版本需要额外确认你项目里用到的插件是否已经适配因为大版本升级往往伴随配置写法的变化老教程里的配置项可能直接失效。另一条是不要盲目追最新。修正版本号最大的那个确实修了更多 bug但如果你是在公司环境里装、需要和同事保持统一那就跟着团队现有版本走。构建工具这东西全组统一比单机最新重要得多——版本不一致导致我本地能打包、你本地报错的情况我遇到过不止一次。至于怎么查当前的最新版本最靠谱的做法是去 Maven 官方站点看发布公告页那里会列出当前推荐版本和维护中的版本线。不建议直接搜maven 下载因为搜出来的很多是几年前的博客里面的版本号早就过期了。2.2 bin 包、src 包以及 zip 和 tar.gz 怎么选下载页面上通常能看到四种组合-bin.zip、-bin.tar.gz、-src.zip、-src.tar.gz。判断方法很简单就看中间那个词。bin是二进制包里面是编译好的可执行文件你装来用就选这个。src是源码包里面是 Maven 自己的源代码那是给想研究它实现或者要自己改的人准备的普通使用者完全不需要。我曾经见过有人下错成 src 包解压后找不到bin目录还以为下载的文件损坏了。后面的压缩格式看操作系统Windows 用.zipLinux 和 macOS 用.tar.gz。虽然 Windows 上也有办法解压 tar.gz但没必要给自己找事。macOS 需要注意一点Safari 下载.tar.gz有时会自动解压成.tar如果你发现解压出来的东西不对先检查一下是不是这个原因。2.3 别跳过哈希校验这一步官方下载页一般会提供每个安装包的哈希值常见的是 SHA-512 或者 SHA-1。这一步大部分人直接跳过我理解因为平时确实很少出问题。但在公司内网环境、或者下载速度异常慢导致文件被截断的情况下装包损坏是真实会发生的而且它损坏后的表现极其迷惑解压出来目录结构看着正常运行时报的错却和文件缺失有关。校验的方法不难。Windows 上用 PowerShell 执行Get-FileHash 文件名 -Algorithm SHA512Linux 上用sha512sum 文件名macOS 上用shasum -a 512 文件名。把输出和官网给的值逐字符比对一致就放心用。这个动作花不到十秒。注意如果官网给的是一长串哈希值比对时注意区分大小写不敏感的情况同时确认你比的是同一个算法。有人拿 SHA-1 的结果去和 SHA-512 的值比当然对不上。3. 解压与路径规划那些一年后才发作的坑解压这一步没什么技术含量但装在哪里、叫什么名字直接影响你后面几个月用得顺不顺。我这一节讲的是选址问题。3.1 安装目录怎么选三条硬性约束第一条约束路径里不要有中文和空格。这是最硬的一条。Maven 内部有很多地方要把路径拼进命令行参数路径里带空格会被当成参数分隔符导致命令被截断。我曾经把 Maven 装在一个叫D:\开发工具\的目录下结果某个插件的执行阶段直接报找不到文件排查了两个小时才定位到是路径中文的问题。后来我给自己定了规矩所有开发工具统一装在一个纯英文、无空格的目录下比如D:\devtools\或者C:\tools\。第二条约束不要装在需要管理员权限才能写入的目录。典型的是C:\Program Files。Maven 运行过程中会往自己的目录里写东西比如某些插件的临时文件权限不足时报错信息往往很隐晦。用普通用户目录或者独立的工具盘更省心。第三条约束目录名带上版本号。比如解压后把文件夹重命名为maven-3.9.6。这么做的好处是将来升级时你可以把新版本解压成maven-3.9.9两个版本共存只需要改环境变量就能切换出问题随时回滚。我吃过亏——早期我不带版本号升级时直接覆盖了旧目录结果新版有个插件不兼容想回退发现旧版已经没了只能重新下载。3.2 环境变量Windows、macOS、Linux 的三种配法Maven 需要在任意目录下都能被调用所以得把它的bin目录加到系统的可执行路径里。三个平台的思路一样操作方式不同。Windows 上的做法分两步。先新建一个系统变量MAVEN_HOME值填 Maven 的解压目录也就是bin的上一级。然后编辑Path变量新增一条%MAVEN_HOME%\bin。用MAVEN_HOME中转而不是直接把完整路径塞进Path是为了将来改版本时只改一处。macOS 和 Linux上编辑用户目录下的 shell 配置文件。现在 macOS 默认是 zsh改~/.zshrc多数 Linux 发行版是 bash改~/.bashrc。追加两行export MAVEN_HOME/opt/devtools/maven-3.9.6 export PATH$MAVEN_HOME/bin:$PATH保存后执行source ~/.zshrc或对应的文件名让它立即生效。这里有个老教程留下的坑必须提一句不要配M2_HOME。很多几年前的文章里会同时让你配MAVEN_HOME和M2_HOME但新版本已经不再使用M2_HOME这个变量了配了不会有任何作用反而会让排查问题时多一层干扰。看到还在要求配M2_HOME的教程基本可以判断是旧内容。3.3 用 mvn -v 做第一次体检新开一个终端窗口一定要新开已打开的窗口不会自动读取你刚改的环境变量这个细节每年都有人踩执行mvn -v正常输出大概是这样的结构第一行是 Maven 的版本号和打包时间第二行是 Maven 的安装目录第三行是 Java 的版本号、供应商和JAVA_HOME指向的路径第四行是默认语言环境和操作系统信息。这份输出里你要核对三件事。Maven home 是否指向你刚解压的那个目录如果指到了别的地方说明你电脑上可能早就有另一个 MavenPATH里的顺序需要调整。Java version 是不是你期望的那个如果不是回去检查JAVA_HOME。OS name 里的架构是 64 位还是 32 位如果显示 32 位而你的系统是 64 位说明装错了 JDK。四条信息全对上安装这一步就算完成了。此时可以再执行一条mvn help:system它会打印出更详细的环境信息包括本地仓库的实际路径、系统属性、环境变量快照。这条命令有个额外作用它是第一次真正触发远程仓库访问的操作如果配置有问题比如镜像地址写错、公司网络需要额外设置在这一步就会暴露而不是等到你构建真实项目时才发现。4. settings.xml真正决定日常体验的地方解压和环境变量只是让mvn这个命令能跑起来真正影响你每天使用感受的是settings.xml这份配置文件。很多人装完就再也没碰过它然后用起来各种别扭。4.1 全局配置与用户配置改哪个谁盖谁settings.xml有两个可能的位置优先级不同。一个是 Maven 安装目录下的conf/settings.xml叫全局配置对这台机器上所有使用该 Maven 的用户生效。另一个是用户目录下的.m2/settings.xmlWindows 上是C:\Users\你的用户名\.m2\settings.xml叫用户配置只对你当前用户生效。两者的关系是覆盖不是合并。同一个配置项如果两处都出现了用户配置会盖掉全局配置。但不同配置项之间是各管各的用户配置里没写的项仍然从全局配置取。实际使用中的建议是开发机只改用户配置全局配置保持原样。理由很实在——将来你升级 Maven新版本解压出来是一份全新的、没被改过的conf目录如果你之前改的是全局配置升级后就得重新改一遍而用户配置独立于安装目录升级完全不受影响。提示用户目录下的.m2/settings.xml默认并不存在需要你自己新建。最省事的做法是把安装目录conf/settings.xml复制一份过去再在副本上改这样所有可选项和注释说明都在改起来有参照。4.2 本地仓库搬家为什么值得改改哪里本地仓库默认在~/.m2/repository。这个位置有两个现实问题一是它在系统盘二是它会一直变大。变大到什么程度我自己的机器上用了一年多、常驻五六个项目的仓库目录占了将近 3 GB。如果你做的是多模块的大项目、依赖树深十几个 GB 也不稀奇。系统盘空间紧张的时候这 3 GB 会很显眼。另外系统盘如果做了定期还原、或者重装系统会格式化仓库跟着一起没了所有依赖都得重新下一遍。改法是在settings.xml里找到localRepository标签把注释去掉填上你想要的绝对路径localRepositoryD:/repos/maven-repository/localRepository两个细节。路径用正斜杠或者双反斜杠单个反斜杠在 XML 里会被当转义符处理。目标目录不需要你手动创建Maven 第一次用到时会自己建但如果父目录不存在某些情况下会报错稳妥起见先手动建好外层目录。改完以后把旧仓库目录里的内容整体搬过去能避免重新下载。搬完之后执行mvn help:evaluate -Dexpressionsettings.localRepository看看输出的路径是不是你新配的那个确认生效。4.3 镜像配置写得对是加速写得错是灾难mirrors这一段是配置文件里最需要小心的地方。它的作用是把对某个远程仓库的请求重定向到你指定的另一个地址。标准写法是在mirrors里加一个mirror包含三个关键子标签id随便起个不重复的名字mirrorOf声明它要接管哪个仓库url填镜像地址。mirror idinternal-mirror/id mirrorOfcentral/mirrorOf urlhttps://你的镜像地址/repository/maven-public//url /mirrormirrorOf这个标签是踩坑重灾区它的取值规则必须搞清楚。取值写法含义适用场景central只接管默认的中央仓库最常用安全推荐*接管所有仓库包括你在 pom 里额外声明的公司统一私服时用个人机器上慎用external:*接管所有非本机地址的仓库需要排除本地仓库的特殊场景repo1,repo2只接管指定的几个仓库 id精确控制*,!repo1接管全部但排除 repo1跳过某个必须走原始地址的仓库很多人图省事直接写*然后在某个项目里添加了公司内部仓库发现怎么都拉不到包——因为*把内部仓库的请求也重定向到了公共镜像上而公共镜像当然没有你公司的私有包。这个问题的现象是报 404说找不到某个内部依赖但依赖坐标明明是对的。我第一次遇到时以为是私服挂了折腾半天才发现是mirrorOf写成了*。所以我的建议是个人开发机用central只有在明确知道自己在干什么的情况下才用*。如果确实需要同时用公共镜像和内部私服就用*,!内部仓库id的排除写法。4.4 一次把编码和编译版本预设好settings.xml里还能配profiles用来预设一些全局生效的属性。有两类属性我建议一开始就配好能省掉后面反复出现的麻烦。一类是编码。Windows 中文环境下控制台默认编码和源码编码经常不一致导致编译时中文注释报警告、日志输出乱码。在 profile 里设上properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties另一类是编译的 JDK 版本。如果你用的 JDK 是 17但项目想编译出兼容 8 的字节码就要告诉编译插件目标版本。这块更推荐写在项目的pom.xml里因为它是项目属性、应该跟着项目走但如果你的机器上所有项目都是同一个 JDK写在settings.xml的 profile 里更省事。配完 profile 记得要在文件末尾的activeProfiles里激活它否则配了等于没配——这也是一个高频疏漏点activeProfiles activeProfilejdk-config/activeProfile /activeProfiles5. 装完之后怎么验证它真的能用mvn -v通过只代表工具装好了不代表它能正常干活。我习惯用一个最小工程做一次端到端验证十来分钟能把大部分潜在问题提前暴露。5.1 从零建一个最小工程跑通全流程新建一个目录在里面创建 Maven 约定的标准结构src/main/java/com/example/然后放一个最简的类package com.example; public class App { public static void main(String[] args) { System.out.println(build ok); } }同目录下写一个最小的pom.xml只需要四样东西modelVersion固定写4.0.0groupId、artifactId、version三坐标自己填再加一个maven.compiler.source和maven.compiler.target指定字节码版本。就这么点内容就够跑了。然后在项目根目录也就是pom.xml所在的位置执行mvn clean package这条命令会依次跑清理、编译、测试没有测试就跳过、打包。第一次执行你会看到 Maven 大量下载插件屏幕上滚过一串Downloading from ...。这一步是最关键的验证点如果镜像配得对、网络通几分钟内就能跑完最后输出BUILD SUCCESStarget目录下出现一个 jar 文件。如果卡在某个下载上不动或者报连接超时问题就在仓库配置回上一节检查。跑通之后还可以试试java -cp target/classes com.example.App看到打印出build ok说明编译产物是完好的。5.2 用 dependency:tree 摸清依赖家底工程一旦引入了依赖mvn dependency:tree就是你最常用的诊断命令。它把整个依赖关系以树形打印出来每一行是一个依赖坐标缩进表示层级。这个命令的实用场景有三个。一是排查我明明没引入这个库怎么它出现在类路径里了树里能看到是谁把它带进来的。二是定位版本冲突被 Maven 裁决掉的低版本会用省略号标记出来你一眼就能看出哪个版本最终生效。三是检查意外的大依赖有时候某个小工具库会拖进来一整个重量级框架发现后可以加exclusions排除掉。配合-Dincludes参数可以只看你关心的分支mvn dependency:tree -Dincludesorg.example:*5.3 和 IDE 对接时容易对不上的三处地方大部分人在 IDE 里用 Maven这里有三处经常出现命令行能跑、IDE 报错的错位。第一处是 Maven 的版本来源。主流 IDE 都自带一份内置的 Maven默认就用内置的。你命令行装的是 3.9.6IDE 用的是它自带的另一个版本两者行为可能不一致。解决办法是在 IDE 的设置里把 Maven home 指向你命令行装的这