刚入行那会儿我身边的人哪懂什么叫构建工具。每做一个项目先建个lib文件夹然后满网找jar包下载下来往里面一扔再手动加到classpath。等哪天同事更新了一个依赖版本整个项目直接跑不起来。直到后来熟悉了Maven才意识到这玩意儿解决的不只是“下载jar包”的问题。这篇博文就围绕“安装、配置Maven”这个主题把从零开始到完全跑通的完整过程讲清楚包括版本选择、环境变量配置、settings.xml核心配置以及我在实际使用中踩过的一些坑。这篇文章适合所有Java开发者尤其是刚接触Maven的人。如果你已经用IDE里的内置Maven跑过项目但对命令行环境和配置细节不熟这篇也能帮你把短板补齐。我会尽量把每个步骤背后的原因讲透而不只是抛出一堆命令让你复制粘贴。1. Maven到底是什么解决的是什么问题1.1 依赖管理的核心痛点做Java开发依赖管理是躲不开的话题。一个稍微有点规模的项目用到的第三方库少说几十个多则上百个。你要是手动管理这些jar包会遇到几个非常头疼的麻烦。第一是版本冲突。A库依赖的某个公共库是1.0版本B库要求同一个公共库是2.0版本你放一个进去另一个就炸放两个进去classpath就乱套。手动管理jar包时这种问题经常让人崩溃。第二是传递依赖。你用了一个库这个库又依赖其他库那些“间接依赖”在手动管理下完全不可见。直到运行时某个类找不到了你才知道原来还少一个jar包。第三是构建流程不统一。有人用IDE跑项目有人用命令行跑编译、打包、测试的流程全凭个人习惯换个人接手就得重新摸索。Maven解决的正是这些问题。它通过一个pom.xml文件声明依赖关系所有jar包都从统一仓库拉取版本由Maven的依赖仲裁机制处理构建流程则通过标准化的生命周期来约束。说白了它把你从“摸索怎么构建项目”里抽离出来让你专心写业务代码。1.2 三个核心概念坐标、仓库、生命周期理解Maven之前建议先搞明白三个概念后面所有配置都围绕它们展开。坐标就是依赖的唯一标识由groupId、artifactId、version三部分组成。groupId一般是公司或组织域名倒写比如com.exampleartifactId是项目或模块名version是版本号。这三者组合在一起就能在全球范围内定位到一个具体的库。这有点像快递地址国家、城市、街道都确定了才能送到正确的位置。仓库是jar包存放的地方分本地仓库和远程仓库。你第一次执行Maven命令时它会去远程仓库下载依赖存到本地仓库里下次再用就直接读取不需要重复下载。中央仓库是Maven官方维护的远程仓库存放了绝大多数开源库国内使用时会配合镜像仓库来加速下载这个后面详细说。生命周期是Maven定义好的一套构建流程包括clean、validate、compile、test、package、install、deploy等阶段。执行mvn package时Maven会按顺序把compile、test、package这些前置阶段全部执行一遍保证构建过程的完整性。1.3 为什么必须有独立安装的Maven有些人会用IDE自带的Maven比如一些主流IDE内置了Maven插件开箱即用。确实对于简单项目来说IDE自带的版本够用了。但我还是建议自己独立安装一份。原因有几个。第一IDE自带的Maven版本是固定的你没法自由升级但项目里用的依赖可能要求更新的Maven版本或者某个插件和当前Maven版本不兼容这时候你就被卡住了。第二现代开发工作流里命令行操作不可避免。CI服务器上跑构建、执行脚本、批量处理项目这些场景都要求命令行里有可用的mvn命令。第三独立安装后你可以自己掌控配置文件的位置全局配置和项目配置分离权限更清晰。所以如果你打算认真搞Java开发别把Maven寄托在IDE上自己在系统里装一份一劳永逸。2. 安装前的关键准备版本与发行包2.1 Maven和JDK版本的匹配关系很多人上来就下载最新版Maven结果发现和JDK版本对不上编译报一堆莫名其妙的错误。Maven本身是Java写的运行它需要一个JDK或JRE环境。不同版本的Maven对JDK版本的要求不一样最新版本的Maven通常要求JDK 8也有一些版本要求JDK 7。可以简单看下面这个对应关系Maven版本最低JDK版本推荐JDK版本Maven 3.6.xJDK 7JDK 8Maven 3.8.xJDK 7JDK 8或11Maven 3.9.xJDK 8JDK 8、11、17Maven 4.xJDK 8JDK 11或17我目前的建议是如果你用的是JDK 11或17直接选Maven 3.9.x如果你还在用JDK 8Maven 3.8.x或者3.9.x都可以。不建议在没有特殊需求的情况下用太老的Maven版本因为新版本在解析依赖、拉取下载方面优化了不少而且对新版本插件的兼容性更好。还有个容易忽略的点JAVA_HOME环境变量必须指向JDK而不是JRE。有些人在Windows上装了个JRE然后JAVA_HOME指过去Maven能启动但某些编译功能会异常。另外如果你的机器上装了多个JDK版本可以在执行Maven命令前临时设置JAVA_HOME来切换这样不用反复改系统环境变量。2.2 下载哪种发行包Maven官网提供了几种格式的发行包包括tar.gz、zip等。tar.gz是Linux和macOS的常用格式zip在Windows上使用比较方便。其实两者内容是一样的只是打包格式不同。选择的时候一个简单原则Windows用zipLinux和macOS用tar.gz。下载时建议选择二进制压缩包即带有bin的发行版而不是源码包。源码包是给那些想自己编译Maven源码的人准备的普通使用者不需要看。具体操作就是在官网的Download页面找到二进制压缩包链接点进去下载即可。下载完成后可以验证一下文件大小和官方提供的SHA-512校验值是否一致。这一步很多人会跳过但对于从网络上下载的工具来说做一次校验没什么坏处。不过如果你是从官方链接直接下载的不校验大概率也没问题。2.3 安装目录规划在解压之前先想好把Maven放在哪个目录这看起来是小事但影响后续升级和管理。Windows上我建议放在一个统一目录比如D:\dev或者C:\dev然后解压得到类似D:\dev\apache-maven-3.9.x这样的目录结构。Linux和macOS上可以放在/opt/maven或者/usr/local目录。关键在于目录命名里保留版本号。这样以后升级Maven时只需要把新版本解压到同一个父目录下然后修改环境变量的指向即可不用担心配置丢失。我见过一些人把Maven直接解压到根目录版本号也不保留升级的时候想原地覆盖又怕出问题最后只能重新解压再配一遍环境变量非常折腾。还有一个目录规划小技巧本地仓库目录不要放在Maven安装目录里面。默认的本地仓库在用户目录下的.m2/repository但你可以改到其他盘符或公共目录。这样即使Maven重新安装或升级本地的依赖缓存还在不会白下载一遍。这个后面配置章节会详细讲。3. 分步实操从解压到验证安装3.1 Windows环境变量配置Windows上配置Maven环境变量主要是两步新建MAVEN_HOME变量再把bin目录加到Path里。先解压下载好的zip压缩包到目标目录比如D:\dev\apache-maven-3.9.6。然后按Win键搜索“环境变量”打开“编辑系统环境变量”点击“环境变量”。在系统变量区域点击“新建”变量名填MAVEN_HOME变量值填D:\dev\apache-maven-3.9.6。接下来找到Path变量双击编辑新建一条%MAVEN_HOME%\bin。这里注意Windows 10以上的系统可以直接用%MAVEN_HOME%\bin这种形式不需要写成绝对路径。点击确定保存所有窗口后重新打开一个新的命令行窗口输入mvn -v如果能显示Maven版本信息就说明配置成功了。这里有个细节配置完环境变量后一定要新开一个命令行窗口不能直接在原来的窗口里测试。因为环境变量的读取是在命令行窗口启动时就确定的旧的窗口里读不到最新配置。我见过好几个人在配置完之后一直用旧窗口测试报“不是内部或外部命令”然后怀疑配置有问题来回折腾了半天。3.2 macOS和Linux环境变量配置macOS和Linux的配置思路类似区别在于你用的Shell是bash还是zsh。新版本macOS默认用zsh所以配置文件是~/.zshrcLinux大部分发行版默认bash用~/.bashrc或者~/.bash_profile。假设你解压到了/opt/maven/apache-maven-3.9.6打开终端执行vim ~/.zshrc或者vim ~/.bashrc在文件末尾加两行内容export MAVEN_HOME/opt/maven/apache-maven-3.9.6 export PATH$MAVEN_HOME/bin:$PATH保存退出后执行source ~/.zshrc让配置生效或者直接关掉终端重新开一个。然后同样执行mvn -v验证。Linux上有时候会遇到权限问题比如你没有/opt目录的写权限这时候可以解压到自己家目录下比如~/apps/apache-maven-3.9.6再把MAVEN_HOME指向那里不需要sudo权限更省事。另外一个建议是如果你同时维护多个开发工具可以把它们的路径都写进同一个配置文件里统一管理避免以后出现PATH变量被覆盖的问题。3.3 验证安装是否成功验证安装最直接的方式就是执行mvn -v看输出。一个正常的输出会包含Maven版本号、使用的JDK版本、以及当前用户目录的信息。我第一次配置完执行这个命令时看到那些信息心里才踏实。mvn -v如果输出中有Maven home、Java version等信息说明基础配置没问题。还有一条命令推荐执行一下mvn help:system。这条命令会触发Maven加载本地仓库配置然后打印系统环境变量。如果配置有问题比如settings.xml格式错误这条命令会立即报错比后续跑项目时才发现问题要快得多。另外我建议你把安装目录下conf/settings.xml这个文件复制一份到.m2目录下。虽然Maven默认也会读取用户目录下的settings.xml但它不会自动创建这个文件。手动复制过去后面所有个人配置都改用户目录下的这一份不碰全局配置这样Maven升级时不会把个人配置覆盖掉。4. 核心配置settings.xml详解4.1 全局配置与用户配置的区别Maven有两级别配置文件存在两个目录。一个是Maven安装目录下的conf/settings.xml这是全局配置另一个是用户目录下的.m2/settings.xml这是用户配置。默认情况下Maven会优先读取用户配置只有用户配置不存在时才读取全局配置。我强烈建议你使用用户配置。原因很简单全局配置在Maven升级时可能会被覆盖用户配置则独立于安装目录升级不丢失。而且用户配置只对当前用户生效不会影响机器上的其他用户。放到团队环境里每个开发者可以有自己的私有配置比如本地仓库地址、镜像设置这些没必要全局共享。手动创建用户配置也很简单。把安装目录conf/settings.xml复制到用户目录下的.m2目录里即可。Windows上用户目录通常是C:\Users\你的用户名macOS和Linux上是/home/你的用户名。注意.m2目录可能是隐藏的文件管理器里需要开启显示隐藏文件才能看到。4.2 本地仓库路径配置settings.xml里一个最常改的地方就是本地仓库路径。默认情况下本地仓库在用户目录下的.m2/repository但这个默认位置有几个问题。如果C盘空间紧张而本地仓库动辄几个GB甚至几十GB默认位置就很麻烦。这时候可以通过localRepository标签指定一个新位置。比如我想把本地仓库放在D盘独立目录可以这样配置localRepositoryD:/maven/repository/localRepositoryLinux/macOS下写成类似这样localRepository/data/maven/repository/localRepository配置完成后执行任意Maven命令Maven就会把依赖下载到这个目录。我建议把本地仓库放到一个独立的数据盘或单独目录这个目录最好定期备份因为里面存的都是下载过的依赖换电脑或者重装系统后能省下大量重新下载的时间。4.3 配置镜像仓库这是安装配置里最关键、也最容易出问题的一步。Maven默认从中央仓库下载依赖但本地网络环境下访问中央仓库的速度非常不稳定下载大文件经常失败或极慢。解决办法是配置一个国内公共Maven镜像仓库通过加速节点来拉取依赖。配置方式是在settings.xml里的mirrors节点下加一个mirror配置mirrors mirror idaliyun-public/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors目前国内几个主流云服务商都提供了Maven公共镜像服务具体地址可以在对应官网搜索“Maven镜像”就能找到。配置好之后Maven访问中央仓库时会被“拦截”转而去请求镜像仓库。mirrorOf字段填central表示只拦截中央仓库的请求其他自定义仓库源不拦截。也可以填*代表拦截所有仓库请求但这种方式一般不太建议除非你确定所有依赖都走镜像。这里有个判断常见问题的思路如果你发现Maven下载依赖时完全不走到镜像先检查mirrorOf的值是否正确。填central是最稳妥的因为绝大多数开源的依赖都是从中央仓库拉取的。另外mirror的id不要重复id重复时Maven会报错或者按顺序匹配第一个可用项。4.4 统一JDK编译级别Maven默认用JDK版本编译代码但有时候你希望代码编译成指定版本比如在JDK 17环境上编译出兼容JDK 11的字节码。这需要在settings.xml里通过profile配置maven.compiler.source和maven.compiler.target。举个例子配置一个默认激活的profile指定编译级别为11profiles profile idjdk-11/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source11/maven.compiler.source maven.compiler.target11/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /profile /profilesmaven.compiler.source表示源码版本maven.compiler.target表示编译后的字节码版本project.build.sourceEncoding则能防止因为编码问题导致的编译乱码。这一项我建议无论如何都要配置一下因为不同操作系统和IDE的默认编码不一致不设置的话项目换台机器容易出现乱码告警。需要注意的是如果项目pom.xml里已经显式配置了maven-compiler-plugin的source和target那么settings.xml里的配置会被项目内的配置覆盖。settings.xml里的这套profile配置只是提供了一个全局默认值项目里没指定的时候才会生效。4.5 其他常用配置项除了上面几个核心配置settings.xml里还有几个平时用得上的配置项。server配置用于私服认证。如果你公司内部有Nexus之类的私有仓库拉取依赖时可能需要认证。格式大致是这样的servers server idnexus-snapshots/id usernameyour-username/username passwordyour-password/password /server /servers这里的id要和pom.xml里repository配置的id保持一致。此外pluginGroups配置用于指定插件组默认自带org.apache.maven.plugins和org.codehaus.mojo一般不需要动。还有mirrors和profiles的优先级问题Maven在解析配置时会遵循用户配置优先于全局配置项目配置优先于用户配置的规则这个顺序搞清楚了排查问题时思路会清晰很多。5. 跑通第一个项目创建、编译、打包5.1 用archetype生成项目骨架配置好Maven之后强烈建议马上跑一个项目验证整个环境是通的别等到项目开发时才暴露问题。Maven提供了一个archetype插件可以从模板生成项目骨架。执行下面这条命令mvn archetype:generate -DgroupIdcom.example -DartifactIdmy-app -DarchetypeArtifactIdmaven-archetype-quickstart -DinteractiveModefalse命令里的groupId就是你坐标里的公司标识artifactId是项目名archetypeArtifactId是模板名称maven-archetype-quickstart是一个最基础的标准项目模板。第一次执行时Maven会下载archetype插件和大量模板文件速度可能比较慢耐心等。执行完成后当前目录下会生成一个my-app文件夹这就是你的第一个Maven项目。如果你用的是命令行界面注意执行命令时先确认当前目录是你想生成项目的地方。5.2 认识标准和目录结构生成的my-app目录结构大概是这样的my-app/ ├── pom.xml └── src/ ├── main/ │ └── java/ │ └── com/example/ │ └── App.java └── test/ └── java/ └── com/example/ └── AppTest.javasrc/main/java放正式代码src/test/java放测试代码这个约定是Maven最核心的“约定优于配置”思想你不需要告诉Maven源码在哪里它默认就在这个位置。只要按照这个目录放代码Maven就能自动完成编译和测试。pom.xml是项目的灵魂所有依赖、插件、构建配置都在这里。手动打开看一下会发现里面除了项目坐标还默认引入了JUnit测试框架的依赖。这个文件以后会频繁改动每次新增依赖都要编辑pom.xml加完依赖后Maven才会去下载对应的jar包。5.3 打包并运行在my-app目录里执行mvn packageMaven会依次执行编译、测试、打包最后在target目录下生成一个jar文件。观察控制台输出你会看到一堆以[INFO]开头的日志比如编译成功、测试成功、打包成功等。如果测试代码有问题构建就会在此阶段失败这是Maven生命周期完整性的体现。打包生成的jar文件名称由artifactId和version拼接而成比如my-app-1.0-SNAPSHOT.jar。直接用java -jar运行这个jar可能不行因为默认的maven-archetype-quickstart生成的jar没有配置主类直接运行会报“没有主清单属性”。要运行它可以手动指定主类java -cp target/my-app-1.0-SNAPSHOT.jar com.example.App或者更彻底一点在pom.xml里配置spring-boot-maven-plugin之类的插件把项目打成可执行jar。对普通学习项目来说手动指定主类就够了。6. 常见问题排查与避坑6.1 mvn不是内部或外部命令这是最常见的入门问题。执行mvn -v时提示找不到命令原因九成是环境变量没配好或者没生效。排查推荐的顺序是先确认MAVEN_HOME指向的路径是否正确就是这个路径下有bin目录再确认Path里有没有%MAVEN_HOME%\bin最后看命令行窗口是不是新开的。如果都确认了还不行打开一个新窗口执行echo %MAVEN_HOME%看能否正确打印变量值。如果打印不出来说明MAVEN_HOME变量本身没生效如果能打印出来但仍然找不到命令再看Path配置。这条排查思路基本上能解决所有环境变量相关的问题。6.2 依赖下载慢或者下载失败镜像配置是这类问题的最优解。如果你没配置任何镜像下载慢很正常。配置了镜像还慢那就要检查镜像地址是否有效、mirrorOf是否匹配。还有个思路配置镜像后Maven并不会主动清理之前下载失败的缓存文件所以如果某次下载失败再执行时建议加-U参数强制更新快照mvn -U clean package这个参数会强制检查远程仓库的最新版本但平时不用加只在需要强制更新时使用。6.3 无效的目标发行版编译时遇到类似“无效的目标发行版: 11”这样的报错说明编译级别的配置和JDK版本不匹配。比如说环境里跑Maven的是JDK 8但配置了编译目标为11JDK 8的javac根本不认识“--release 11”这个选项。解决办法是让运行Maven的JDK版本大于等于编译目标版本。如果项目需要编译成高版本字节码就安装对应版本的JDK并把JAVA_HOME指向那个JDK。或者反过来把编译目标降到当前JDK支持的版本。检查时执行mvn -v看显示的Java version确认用的是哪个JDK再看settings.xml和pom.xml里的编译级别两相对照问题基本就能看出来。6.4 依赖冲突怎么排查依赖冲突的经典表现是编译时一切正常运行时却抛出ClassNotFoundException或者NoSuchMethodError。这种错误往往和某个传递依赖的版本不对有关。Maven默认的仲裁策略是最短路径优先但有时会出现不同版本的同一个依赖被同时引入。排查依赖树推荐用这条命令mvn dependency:tree它会递归列出所有依赖以及版本信息能直观看到同一个库被引入了几个版本。想看更深层的原因可以加参数查看详细依赖路径比如mvn dependency:tree -Dverbose。确认了冲突依赖后在pom.xml里通过exclusion排除掉不需要的版本或者用dependencyManagement锁定统一版本。这个技能在项目后期维护时特别有用。7. 实操经验一些值得保留的习惯最后分享一些长期使用Maven积累下来的操作习惯不是特别系统但每个都是实打实用过的经验。本地仓库和settings.xml建议一起备份。换电脑时把.m2目录里的settings.xml和repository文件夹整体拷走新环境里只需要改一下localRepository路径就能直接用几百个依赖不需要重新下载。我每次换开发机都这么做节省的时间非常可观。尽量不要使用默认的中央仓库直接下载依赖。无论你在哪个网络环境下配置一个速度快的镜像仓库都不会浪费时间这是Maven体验感提升最明显的一步。而且不要把镜像配置局限在中央仓库如果公司有私服优先用私服的镜像配置保持一致性和可控性。pom.xml里的依赖版本尽量用properties属性统一管理而不是在每个依赖里写死版本号。这样升级依赖时只改一处即可不用全文搜索替换。比如properties junit.version5.10.0/junit.version /properties这只是个小习惯但多个模块时能省不少事。使用命令行构建项目时我会习惯性地加上clean比如mvn clean package而不是直接mvn package。这样能保证每次构建都是从干净状态开始避免残留target目录里旧的class文件影响判断。虽然多花几秒但排查问题时能少很多干扰因素。Maven的安装配置其实是一次性的工作配置好了就长期受益。真正花时间的还是理解它背后的依赖管理和生命周期机制。刚开始上手时遇到报错不要慌多看日志日志里基本都会指明是哪一步出了问题定位到具体环节解决起来就快很多。 
长河君 · 2026/10/18 10:36:29 · 阅读 1.2k Maven安装配置详解：从环境变量、settings.xml到依赖管理实战
刚入行那会儿我身边的人哪懂什么叫构建工具。每做一个项目先建个lib文件夹然后满网找jar包下载下来往里面一扔再手动加到classpath。等哪天同事更新了一个依赖版本整个项目直接跑不起来。直到后来熟悉了Maven才意识到这玩意儿解决的不只是“下载jar包”的问题。这篇博文就围绕“安装、配置Maven”这个主题把从零开始到完全跑通的完整过程讲清楚包括版本选择、环境变量配置、settings.xml核心配置以及我在实际使用中踩过的一些坑。这篇文章适合所有Java开发者尤其是刚接触Maven的人。如果你已经用IDE里的内置Maven跑过项目但对命令行环境和配置细节不熟这篇也能帮你把短板补齐。我会尽量把每个步骤背后的原因讲透而不只是抛出一堆命令让你复制粘贴。1. Maven到底是什么解决的是什么问题1.1 依赖管理的核心痛点做Java开发依赖管理是躲不开的话题。一个稍微有点规模的项目用到的第三方库少说几十个多则上百个。你要是手动管理这些jar包会遇到几个非常头疼的麻烦。第一是版本冲突。A库依赖的某个公共库是1.0版本B库要求同一个公共库是2.0版本你放一个进去另一个就炸放两个进去classpath就乱套。手动管理jar包时这种问题经常让人崩溃。第二是传递依赖。你用了一个库这个库又依赖其他库那些“间接依赖”在手动管理下完全不可见。直到运行时某个类找不到了你才知道原来还少一个jar包。第三是构建流程不统一。有人用IDE跑项目有人用命令行跑编译、打包、测试的流程全凭个人习惯换个人接手就得重新摸索。Maven解决的正是这些问题。它通过一个pom.xml文件声明依赖关系所有jar包都从统一仓库拉取版本由Maven的依赖仲裁机制处理构建流程则通过标准化的生命周期来约束。说白了它把你从“摸索怎么构建项目”里抽离出来让你专心写业务代码。1.2 三个核心概念坐标、仓库、生命周期理解Maven之前建议先搞明白三个概念后面所有配置都围绕它们展开。坐标就是依赖的唯一标识由groupId、artifactId、version三部分组成。groupId一般是公司或组织域名倒写比如com.exampleartifactId是项目或模块名version是版本号。这三者组合在一起就能在全球范围内定位到一个具体的库。这有点像快递地址国家、城市、街道都确定了才能送到正确的位置。仓库是jar包存放的地方分本地仓库和远程仓库。你第一次执行Maven命令时它会去远程仓库下载依赖存到本地仓库里下次再用就直接读取不需要重复下载。中央仓库是Maven官方维护的远程仓库存放了绝大多数开源库国内使用时会配合镜像仓库来加速下载这个后面详细说。生命周期是Maven定义好的一套构建流程包括clean、validate、compile、test、package、install、deploy等阶段。执行mvn package时Maven会按顺序把compile、test、package这些前置阶段全部执行一遍保证构建过程的完整性。1.3 为什么必须有独立安装的Maven有些人会用IDE自带的Maven比如一些主流IDE内置了Maven插件开箱即用。确实对于简单项目来说IDE自带的版本够用了。但我还是建议自己独立安装一份。原因有几个。第一IDE自带的Maven版本是固定的你没法自由升级但项目里用的依赖可能要求更新的Maven版本或者某个插件和当前Maven版本不兼容这时候你就被卡住了。第二现代开发工作流里命令行操作不可避免。CI服务器上跑构建、执行脚本、批量处理项目这些场景都要求命令行里有可用的mvn命令。第三独立安装后你可以自己掌控配置文件的位置全局配置和项目配置分离权限更清晰。所以如果你打算认真搞Java开发别把Maven寄托在IDE上自己在系统里装一份一劳永逸。2. 安装前的关键准备版本与发行包2.1 Maven和JDK版本的匹配关系很多人上来就下载最新版Maven结果发现和JDK版本对不上编译报一堆莫名其妙的错误。Maven本身是Java写的运行它需要一个JDK或JRE环境。不同版本的Maven对JDK版本的要求不一样最新版本的Maven通常要求JDK 8也有一些版本要求JDK 7。可以简单看下面这个对应关系Maven版本最低JDK版本推荐JDK版本Maven 3.6.xJDK 7JDK 8Maven 3.8.xJDK 7JDK 8或11Maven 3.9.xJDK 8JDK 8、11、17Maven 4.xJDK 8JDK 11或17我目前的建议是如果你用的是JDK 11或17直接选Maven 3.9.x如果你还在用JDK 8Maven 3.8.x或者3.9.x都可以。不建议在没有特殊需求的情况下用太老的Maven版本因为新版本在解析依赖、拉取下载方面优化了不少而且对新版本插件的兼容性更好。还有个容易忽略的点JAVA_HOME环境变量必须指向JDK而不是JRE。有些人在Windows上装了个JRE然后JAVA_HOME指过去Maven能启动但某些编译功能会异常。另外如果你的机器上装了多个JDK版本可以在执行Maven命令前临时设置JAVA_HOME来切换这样不用反复改系统环境变量。2.2 下载哪种发行包Maven官网提供了几种格式的发行包包括tar.gz、zip等。tar.gz是Linux和macOS的常用格式zip在Windows上使用比较方便。其实两者内容是一样的只是打包格式不同。选择的时候一个简单原则Windows用zipLinux和macOS用tar.gz。下载时建议选择二进制压缩包即带有bin的发行版而不是源码包。源码包是给那些想自己编译Maven源码的人准备的普通使用者不需要看。具体操作就是在官网的Download页面找到二进制压缩包链接点进去下载即可。下载完成后可以验证一下文件大小和官方提供的SHA-512校验值是否一致。这一步很多人会跳过但对于从网络上下载的工具来说做一次校验没什么坏处。不过如果你是从官方链接直接下载的不校验大概率也没问题。2.3 安装目录规划在解压之前先想好把Maven放在哪个目录这看起来是小事但影响后续升级和管理。Windows上我建议放在一个统一目录比如D:\dev或者C:\dev然后解压得到类似D:\dev\apache-maven-3.9.x这样的目录结构。Linux和macOS上可以放在/opt/maven或者/usr/local目录。关键在于目录命名里保留版本号。这样以后升级Maven时只需要把新版本解压到同一个父目录下然后修改环境变量的指向即可不用担心配置丢失。我见过一些人把Maven直接解压到根目录版本号也不保留升级的时候想原地覆盖又怕出问题最后只能重新解压再配一遍环境变量非常折腾。还有一个目录规划小技巧本地仓库目录不要放在Maven安装目录里面。默认的本地仓库在用户目录下的.m2/repository但你可以改到其他盘符或公共目录。这样即使Maven重新安装或升级本地的依赖缓存还在不会白下载一遍。这个后面配置章节会详细讲。3. 分步实操从解压到验证安装3.1 Windows环境变量配置Windows上配置Maven环境变量主要是两步新建MAVEN_HOME变量再把bin目录加到Path里。先解压下载好的zip压缩包到目标目录比如D:\dev\apache-maven-3.9.6。然后按Win键搜索“环境变量”打开“编辑系统环境变量”点击“环境变量”。在系统变量区域点击“新建”变量名填MAVEN_HOME变量值填D:\dev\apache-maven-3.9.6。接下来找到Path变量双击编辑新建一条%MAVEN_HOME%\bin。这里注意Windows 10以上的系统可以直接用%MAVEN_HOME%\bin这种形式不需要写成绝对路径。点击确定保存所有窗口后重新打开一个新的命令行窗口输入mvn -v如果能显示Maven版本信息就说明配置成功了。这里有个细节配置完环境变量后一定要新开一个命令行窗口不能直接在原来的窗口里测试。因为环境变量的读取是在命令行窗口启动时就确定的旧的窗口里读不到最新配置。我见过好几个人在配置完之后一直用旧窗口测试报“不是内部或外部命令”然后怀疑配置有问题来回折腾了半天。3.2 macOS和Linux环境变量配置macOS和Linux的配置思路类似区别在于你用的Shell是bash还是zsh。新版本macOS默认用zsh所以配置文件是~/.zshrcLinux大部分发行版默认bash用~/.bashrc或者~/.bash_profile。假设你解压到了/opt/maven/apache-maven-3.9.6打开终端执行vim ~/.zshrc或者vim ~/.bashrc在文件末尾加两行内容export MAVEN_HOME/opt/maven/apache-maven-3.9.6 export PATH$MAVEN_HOME/bin:$PATH保存退出后执行source ~/.zshrc让配置生效或者直接关掉终端重新开一个。然后同样执行mvn -v验证。Linux上有时候会遇到权限问题比如你没有/opt目录的写权限这时候可以解压到自己家目录下比如~/apps/apache-maven-3.9.6再把MAVEN_HOME指向那里不需要sudo权限更省事。另外一个建议是如果你同时维护多个开发工具可以把它们的路径都写进同一个配置文件里统一管理避免以后出现PATH变量被覆盖的问题。3.3 验证安装是否成功验证安装最直接的方式就是执行mvn -v看输出。一个正常的输出会包含Maven版本号、使用的JDK版本、以及当前用户目录的信息。我第一次配置完执行这个命令时看到那些信息心里才踏实。mvn -v如果输出中有Maven home、Java version等信息说明基础配置没问题。还有一条命令推荐执行一下mvn help:system。这条命令会触发Maven加载本地仓库配置然后打印系统环境变量。如果配置有问题比如settings.xml格式错误这条命令会立即报错比后续跑项目时才发现问题要快得多。另外我建议你把安装目录下conf/settings.xml这个文件复制一份到.m2目录下。虽然Maven默认也会读取用户目录下的settings.xml但它不会自动创建这个文件。手动复制过去后面所有个人配置都改用户目录下的这一份不碰全局配置这样Maven升级时不会把个人配置覆盖掉。4. 核心配置settings.xml详解4.1 全局配置与用户配置的区别Maven有两级别配置文件存在两个目录。一个是Maven安装目录下的conf/settings.xml这是全局配置另一个是用户目录下的.m2/settings.xml这是用户配置。默认情况下Maven会优先读取用户配置只有用户配置不存在时才读取全局配置。我强烈建议你使用用户配置。原因很简单全局配置在Maven升级时可能会被覆盖用户配置则独立于安装目录升级不丢失。而且用户配置只对当前用户生效不会影响机器上的其他用户。放到团队环境里每个开发者可以有自己的私有配置比如本地仓库地址、镜像设置这些没必要全局共享。手动创建用户配置也很简单。把安装目录conf/settings.xml复制到用户目录下的.m2目录里即可。Windows上用户目录通常是C:\Users\你的用户名macOS和Linux上是/home/你的用户名。注意.m2目录可能是隐藏的文件管理器里需要开启显示隐藏文件才能看到。4.2 本地仓库路径配置settings.xml里一个最常改的地方就是本地仓库路径。默认情况下本地仓库在用户目录下的.m2/repository但这个默认位置有几个问题。如果C盘空间紧张而本地仓库动辄几个GB甚至几十GB默认位置就很麻烦。这时候可以通过localRepository标签指定一个新位置。比如我想把本地仓库放在D盘独立目录可以这样配置localRepositoryD:/maven/repository/localRepositoryLinux/macOS下写成类似这样localRepository/data/maven/repository/localRepository配置完成后执行任意Maven命令Maven就会把依赖下载到这个目录。我建议把本地仓库放到一个独立的数据盘或单独目录这个目录最好定期备份因为里面存的都是下载过的依赖换电脑或者重装系统后能省下大量重新下载的时间。4.3 配置镜像仓库这是安装配置里最关键、也最容易出问题的一步。Maven默认从中央仓库下载依赖但本地网络环境下访问中央仓库的速度非常不稳定下载大文件经常失败或极慢。解决办法是配置一个国内公共Maven镜像仓库通过加速节点来拉取依赖。配置方式是在settings.xml里的mirrors节点下加一个mirror配置mirrors mirror idaliyun-public/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors目前国内几个主流云服务商都提供了Maven公共镜像服务具体地址可以在对应官网搜索“Maven镜像”就能找到。配置好之后Maven访问中央仓库时会被“拦截”转而去请求镜像仓库。mirrorOf字段填central表示只拦截中央仓库的请求其他自定义仓库源不拦截。也可以填*代表拦截所有仓库请求但这种方式一般不太建议除非你确定所有依赖都走镜像。这里有个判断常见问题的思路如果你发现Maven下载依赖时完全不走到镜像先检查mirrorOf的值是否正确。填central是最稳妥的因为绝大多数开源的依赖都是从中央仓库拉取的。另外mirror的id不要重复id重复时Maven会报错或者按顺序匹配第一个可用项。4.4 统一JDK编译级别Maven默认用JDK版本编译代码但有时候你希望代码编译成指定版本比如在JDK 17环境上编译出兼容JDK 11的字节码。这需要在settings.xml里通过profile配置maven.compiler.source和maven.compiler.target。举个例子配置一个默认激活的profile指定编译级别为11profiles profile idjdk-11/id activation activeByDefaulttrue/activeByDefault /activation properties maven.compiler.source11/maven.compiler.source maven.compiler.target11/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /profile /profilesmaven.compiler.source表示源码版本maven.compiler.target表示编译后的字节码版本project.build.sourceEncoding则能防止因为编码问题导致的编译乱码。这一项我建议无论如何都要配置一下因为不同操作系统和IDE的默认编码不一致不设置的话项目换台机器容易出现乱码告警。需要注意的是如果项目pom.xml里已经显式配置了maven-compiler-plugin的source和target那么settings.xml里的配置会被项目内的配置覆盖。settings.xml里的这套profile配置只是提供了一个全局默认值项目里没指定的时候才会生效。4.5 其他常用配置项除了上面几个核心配置settings.xml里还有几个平时用得上的配置项。server配置用于私服认证。如果你公司内部有Nexus之类的私有仓库拉取依赖时可能需要认证。格式大致是这样的servers server idnexus-snapshots/id usernameyour-username/username passwordyour-password/password /server /servers这里的id要和pom.xml里repository配置的id保持一致。此外pluginGroups配置用于指定插件组默认自带org.apache.maven.plugins和org.codehaus.mojo一般不需要动。还有mirrors和profiles的优先级问题Maven在解析配置时会遵循用户配置优先于全局配置项目配置优先于用户配置的规则这个顺序搞清楚了排查问题时思路会清晰很多。5. 跑通第一个项目创建、编译、打包5.1 用archetype生成项目骨架配置好Maven之后强烈建议马上跑一个项目验证整个环境是通的别等到项目开发时才暴露问题。Maven提供了一个archetype插件可以从模板生成项目骨架。执行下面这条命令mvn archetype:generate -DgroupIdcom.example -DartifactIdmy-app -DarchetypeArtifactIdmaven-archetype-quickstart -DinteractiveModefalse命令里的groupId就是你坐标里的公司标识artifactId是项目名archetypeArtifactId是模板名称maven-archetype-quickstart是一个最基础的标准项目模板。第一次执行时Maven会下载archetype插件和大量模板文件速度可能比较慢耐心等。执行完成后当前目录下会生成一个my-app文件夹这就是你的第一个Maven项目。如果你用的是命令行界面注意执行命令时先确认当前目录是你想生成项目的地方。5.2 认识标准和目录结构生成的my-app目录结构大概是这样的my-app/ ├── pom.xml └── src/ ├── main/ │ └── java/ │ └── com/example/ │ └── App.java └── test/ └── java/ └── com/example/ └── AppTest.javasrc/main/java放正式代码src/test/java放测试代码这个约定是Maven最核心的“约定优于配置”思想你不需要告诉Maven源码在哪里它默认就在这个位置。只要按照这个目录放代码Maven就能自动完成编译和测试。pom.xml是项目的灵魂所有依赖、插件、构建配置都在这里。手动打开看一下会发现里面除了项目坐标还默认引入了JUnit测试框架的依赖。这个文件以后会频繁改动每次新增依赖都要编辑pom.xml加完依赖后Maven才会去下载对应的jar包。5.3 打包并运行在my-app目录里执行mvn packageMaven会依次执行编译、测试、打包最后在target目录下生成一个jar文件。观察控制台输出你会看到一堆以[INFO]开头的日志比如编译成功、测试成功、打包成功等。如果测试代码有问题构建就会在此阶段失败这是Maven生命周期完整性的体现。打包生成的jar文件名称由artifactId和version拼接而成比如my-app-1.0-SNAPSHOT.jar。直接用java -jar运行这个jar可能不行因为默认的maven-archetype-quickstart生成的jar没有配置主类直接运行会报“没有主清单属性”。要运行它可以手动指定主类java -cp target/my-app-1.0-SNAPSHOT.jar com.example.App或者更彻底一点在pom.xml里配置spring-boot-maven-plugin之类的插件把项目打成可执行jar。对普通学习项目来说手动指定主类就够了。6. 常见问题排查与避坑6.1 mvn不是内部或外部命令这是最常见的入门问题。执行mvn -v时提示找不到命令原因九成是环境变量没配好或者没生效。排查推荐的顺序是先确认MAVEN_HOME指向的路径是否正确就是这个路径下有bin目录再确认Path里有没有%MAVEN_HOME%\bin最后看命令行窗口是不是新开的。如果都确认了还不行打开一个新窗口执行echo %MAVEN_HOME%看能否正确打印变量值。如果打印不出来说明MAVEN_HOME变量本身没生效如果能打印出来但仍然找不到命令再看Path配置。这条排查思路基本上能解决所有环境变量相关的问题。6.2 依赖下载慢或者下载失败镜像配置是这类问题的最优解。如果你没配置任何镜像下载慢很正常。配置了镜像还慢那就要检查镜像地址是否有效、mirrorOf是否匹配。还有个思路配置镜像后Maven并不会主动清理之前下载失败的缓存文件所以如果某次下载失败再执行时建议加-U参数强制更新快照mvn -U clean package这个参数会强制检查远程仓库的最新版本但平时不用加只在需要强制更新时使用。6.3 无效的目标发行版编译时遇到类似“无效的目标发行版: 11”这样的报错说明编译级别的配置和JDK版本不匹配。比如说环境里跑Maven的是JDK 8但配置了编译目标为11JDK 8的javac根本不认识“--release 11”这个选项。解决办法是让运行Maven的JDK版本大于等于编译目标版本。如果项目需要编译成高版本字节码就安装对应版本的JDK并把JAVA_HOME指向那个JDK。或者反过来把编译目标降到当前JDK支持的版本。检查时执行mvn -v看显示的Java version确认用的是哪个JDK再看settings.xml和pom.xml里的编译级别两相对照问题基本就能看出来。6.4 依赖冲突怎么排查依赖冲突的经典表现是编译时一切正常运行时却抛出ClassNotFoundException或者NoSuchMethodError。这种错误往往和某个传递依赖的版本不对有关。Maven默认的仲裁策略是最短路径优先但有时会出现不同版本的同一个依赖被同时引入。排查依赖树推荐用这条命令mvn dependency:tree它会递归列出所有依赖以及版本信息能直观看到同一个库被引入了几个版本。想看更深层的原因可以加参数查看详细依赖路径比如mvn dependency:tree -Dverbose。确认了冲突依赖后在pom.xml里通过exclusion排除掉不需要的版本或者用dependencyManagement锁定统一版本。这个技能在项目后期维护时特别有用。7. 实操经验一些值得保留的习惯最后分享一些长期使用Maven积累下来的操作习惯不是特别系统但每个都是实打实用过的经验。本地仓库和settings.xml建议一起备份。换电脑时把.m2目录里的settings.xml和repository文件夹整体拷走新环境里只需要改一下localRepository路径就能直接用几百个依赖不需要重新下载。我每次换开发机都这么做节省的时间非常可观。尽量不要使用默认的中央仓库直接下载依赖。无论你在哪个网络环境下配置一个速度快的镜像仓库都不会浪费时间这是Maven体验感提升最明显的一步。而且不要把镜像配置局限在中央仓库如果公司有私服优先用私服的镜像配置保持一致性和可控性。pom.xml里的依赖版本尽量用properties属性统一管理而不是在每个依赖里写死版本号。这样升级依赖时只改一处即可不用全文搜索替换。比如properties junit.version5.10.0/junit.version /properties这只是个小习惯但多个模块时能省不少事。使用命令行构建项目时我会习惯性地加上clean比如mvn clean package而不是直接mvn package。这样能保证每次构建都是从干净状态开始避免残留target目录里旧的class文件影响判断。虽然多花几秒但排查问题时能少很多干扰因素。Maven的安装配置其实是一次性的工作配置好了就长期受益。真正花时间的还是理解它背后的依赖管理和生命周期机制。刚开始上手时遇到报错不要慌多看日志日志里基本都会指明是哪一步出了问题定位到具体环节解决起来就快很多。