剛開始用Maven時(shí)我以為在Windows上裝好就是下載、解壓、配環(huán)境變量然后敲幾個(gè)命令完事。結(jié)果第一次在一臺新電腦上配置卡了快一上午。后來發(fā)現(xiàn)不是下載的包不對而是JAVA_HOME被配成了JRE的路徑Maven死活起不來。這篇文章就把整個(gè)Windows下Maven安裝和使用的過程完整整理一遍從版本選擇、環(huán)境變量、settings.xml到第一個(gè)項(xiàng)目的完整構(gòu)建流程以及幾個(gè)非常容易踩的坑給同樣準(zhǔn)備入門的讀者參考。這種環(huán)境安裝類的事情網(wǎng)上教程很多但大多是“照著敲能跑、換個(gè)環(huán)境就不行”。我希望這篇文章能讓你明白每一步在做什么、為什么要這么做這樣遇到問題時(shí)不至于兩眼一抹黑。1. Windows下裝Maven前先把這幾個(gè)底層問題想清楚1.1 Maven不是“裝個(gè)包”而已很多初學(xué)者的第一反應(yīng)是Maven就是用來下載依賴的工具。這個(gè)理解沒錯(cuò)但不完整。Maven真正解決的是構(gòu)建流程的標(biāo)準(zhǔn)化問題項(xiàng)目用什么目錄結(jié)構(gòu)、編譯用哪個(gè)JDK版本、測試怎么執(zhí)行、最終打成JAR包還是WAR包這些繁瑣的事情通過一套約定就能統(tǒng)一處理。把Maven裝好意味著你的項(xiàng)目從源代碼變成可運(yùn)行產(chǎn)物的完整生命周期有了可復(fù)現(xiàn)的腳本。團(tuán)隊(duì)里任何一個(gè)人拿到項(xiàng)目執(zhí)行同一套命令就能得到同樣的結(jié)果。這也是為什么Java項(xiàng)目幾乎都會配一個(gè)pom.xml。1.2 版本匹配JDK版本決定Maven版本上限我見過不少人是隨便下一個(gè)Maven版本報(bào)錯(cuò)了才開始懷疑環(huán)境。這里有個(gè)很基礎(chǔ)的匹配關(guān)系Maven本身是用Java寫的運(yùn)行Maven需要本機(jī)裝有JDK而且不同Maven版本對JDK版本的要求不同。目前比較常用的Maven 3.6.x要求JDK 1.7以上Maven 3.8.x和3.9.x要求JDK 8以上。如果你用的是Maven 3.9系列JDK 8、11、17、21一般都沒問題但如果你本機(jī)只裝了JDK 1.6或更老那就只能找老版本的Maven這不現(xiàn)實(shí)建議直接升級JDK。具體選哪個(gè)版本我會建議選最新的Maven 3.9.x穩(wěn)定版。原因有兩個(gè)一是和現(xiàn)代JDK的兼容性更好二是3.x系列在Windows下的使用經(jīng)驗(yàn)最豐富遇到問題容易搜到解決方案。別去嘗鮮Maven 4.x除非你想當(dāng)小白鼠。1.3 確認(rèn)JAVA_HOME指向JDK而不是JRE這是Windows下最常見、也最隱蔽的一個(gè)坑。很多Windows系統(tǒng)的機(jī)器在安裝JDK后其實(shí)還帶著一個(gè)單獨(dú)的JRE。如果你在環(huán)境變量里把JAVA_HOME配到了JRE目錄Maven啟動(dòng)時(shí)會直接提示找不到編譯器環(huán)境或者干脆報(bào)出奇怪錯(cuò)誤。檢查方法很簡單在命令行執(zhí)行echo %JAVA_HOME%正常情況下應(yīng)該指向類似C:\Program Files\Java\jdk-17這樣的路徑而不是C:\Program Files\Java\jre17。可以用下面這張表快速核對檢查項(xiàng)命令期望結(jié)果Java版本java -version輸出中包含jdk版本信息JAVA_HOME路徑echo %JAVA_HOME%指向JDK安裝目錄而非JRE目錄編譯命令javac -version能正常輸出版本號如果javac命令提示找不到說明Path里沒有JDK的bin目錄這在后面配置環(huán)境變量時(shí)會一并解決。2. 下載解壓與目錄結(jié)構(gòu)裝到C盤外后面會省很多事2.1 下載時(shí)別選錯(cuò)包bin.zip與src.zip去Maven官網(wǎng)的下載頁面會看到一連串文件。需要選擇的是apache-maven-3.9.x-bin.zip這才是可直接運(yùn)行的二進(jìn)制發(fā)行包。旁邊那些-src.zip是源碼包下載下來沒法直接運(yùn)行。Windows用戶不要點(diǎn)tar.gz那是給Linux和macOS準(zhǔn)備的Windows下解壓不是不行但沒必要。下載完成后得到一個(gè)zip壓縮包解壓即可不需要安裝程序。Maven本身是綠色軟件這點(diǎn)和Linux上的使用習(xí)慣很像。2.2 解壓后目錄結(jié)構(gòu)速覽解壓后你會看到一個(gè)以版本號命名的文件夾比如apache-maven-3.9.6。打開里面是這樣的apache-maven-3.9.6/ ├── bin/ # mvn可執(zhí)行腳本 ├── conf/ # 核心配置文件settings.xml ├── lib/ # Maven運(yùn)行所需的jar包 └── boot/ # Maven自身啟動(dòng)的類加載器初學(xué)者最容易忽略的是conf/settings.xml和bin/mvn.cmd。前者是全局配置文件本地倉庫位置、鏡像源、代理信息都在這里改后者是Windows下的啟動(dòng)腳本環(huán)境變量驗(yàn)證時(shí)看的就是它。2.3 目錄路徑的兩個(gè)忌諱解壓位置看起來無所謂但實(shí)際在Windows下有兩個(gè)忌諱第一路徑不要帶中文和空格。比如D:\軟件\maven這種路徑在某些舊版工具鏈里會出現(xiàn)編碼或路徑解析問題。建議放在D:\tools\apache-maven-3.9.6這樣的純英文路徑下。第二盡量不要裝到C盤系統(tǒng)盤。Maven的本地倉庫默認(rèn)是在用戶目錄下的.m2文件夾一旦項(xiàng)目多了依賴包體積會迅速膨脹。C盤空間緊張會拖累系統(tǒng)。如果你把Maven本身也放在C盤后面想挪會很麻煩。3. 環(huán)境變量設(shè)置與驗(yàn)證這一步翻車概率最高3.1 從新建MAVEN_HOME到修改Path解壓完并不代表裝好了還差最關(guān)鍵的一步環(huán)境變量。Windows下配置Maven環(huán)境變量需要兩個(gè)動(dòng)作。右鍵“此電腦” - 屬性 - 高級系統(tǒng)設(shè)置 - 環(huán)境變量在“系統(tǒng)變量”區(qū)域點(diǎn)擊“新建”變量名填MAVEN_HOME變量值填Maven的解壓路徑。比如MAVEN_HOME D:\tools\apache-maven-3.9.6然后在已有的Path變量里追加一條%MAVEN_HOME%\bin為什么要專門建一個(gè)MAVEN_HOME再引用而不是直接寫完整路徑一是之后升級Maven版本時(shí)只需要改MAVEN_HOME這一個(gè)地方二是很多工程化工具會自動(dòng)讀取MAVEN_HOME環(huán)境變量提前配好能省不少事。3.2 命令行驗(yàn)證mvn -v 輸出應(yīng)該長什么樣配置完成后重新打開一個(gè)命令行窗口注意舊窗口可能不會刷新環(huán)境變量執(zhí)行mvn -v正常情況下會輸出一段信息。重點(diǎn)看兩行Apache Maven 3.9.6 (... Maven home: D:\tools\apache-maven-3.9.6 Java version: 17.0.10, vendor: ... Java home: C:\Program Files\Java\jdk-17Maven home對Java home對說明環(huán)境變量配置成功。如果輸出的是“不是內(nèi)部或外部命令”大概率是Path沒配置好或者命令行窗口沒重開。3.3 驗(yàn)證失敗的常見原因排查現(xiàn)象可能原因處理方式mvn 不是內(nèi)部或外部命令Path中未包含%MAVEN_HOME%\bin重新檢查PathMaven啟動(dòng)報(bào)錯(cuò)JAVA_HOME變量不存在或指向錯(cuò)誤確認(rèn)JAVA_HOME指向JDK輸出亂碼控制臺編碼問題后續(xù)統(tǒng)一處理Java version顯示的是舊版本JDK版本沖突檢查Path中是否有多余的Java路徑我在實(shí)際中遇到過一種很隱蔽的情況機(jī)器上裝了多個(gè)JDKPath里既有JDK 8的路徑又有JDK 17的路徑導(dǎo)致Maven啟動(dòng)時(shí)用了錯(cuò)誤版本。解決辦法是在Path里把希望使用的JDK bin目錄排到前面或者干脆把多余的JDK環(huán)境變量清理干凈。4. settings.xml才是安裝的重頭戲本地倉庫和鏡像配置4.1 先搞清楚settings.xml什么時(shí)候生效裝好Maven后大多數(shù)人直接就打開項(xiàng)目開始下載依賴。這時(shí)候如果發(fā)現(xiàn)下載特別慢或者依賴很難拉全問題基本都出在Maven的配置文件上。Maven有兩個(gè)層級的settings.xml全局配置文件在%MAVEN_HOME%\conf\settings.xml用戶級配置文件在C:\Users\用戶名\.m2\settings.xml。如果兩個(gè)都存在用戶級的會覆蓋全局配置。實(shí)際使用中我更建議直接改全局配置文件因?yàn)橛脩艏壍奈募粫詣?dòng)創(chuàng)建很多初學(xué)者根本不知道它的存在。4.2 修改localRepository把依賴倉庫挪出C盤打開conf目錄下的settings.xml找到下面這段默認(rèn)注釋內(nèi)容localRepository${user.home}/.m2/repository/localRepository默認(rèn)情況下所有下載下來的依賴jar包都會存到用戶目錄的.m2/repository文件夾里。這有兩個(gè)問題一是C盤空間壓力大二是一旦系統(tǒng)重裝這些依賴全沒。我的做法是把它改成D盤的一個(gè)固定目錄localRepositoryD:\maven-repo/localRepository改完后本地倉庫就統(tǒng)一放到D盤。以后重裝系統(tǒng)、換Maven版本只要路徑不變依賴包還能繼續(xù)使用省去重新下載的麻煩。注意改完這個(gè)路徑后第一次執(zhí)行Maven命令會自動(dòng)創(chuàng)建該目錄不需要手動(dòng)創(chuàng)建。4.3 鏡像源配置解決國內(nèi)下載慢的問題Maven默認(rèn)從中央倉庫下載依賴這個(gè)倉庫服務(wù)器在國外國內(nèi)訪問經(jīng)常很慢或者直接卡住。解決思路很直接配置一個(gè)國內(nèi)公共倉庫鏡像。在settings.xml的mirrors標(biāo)簽內(nèi)添加一個(gè)mirror節(jié)點(diǎn)。這里以國內(nèi)常用的公共倉庫地址為例mirror idpublic-mirror/id mirrorOfcentral/mirrorOf namePublic Mirror/name urlhttps://maven.aliyun.com/repository/public/url /mirror這里的關(guān)鍵是mirrorOfcentral/mirrorOf表示所有對中央倉庫的請求都走這個(gè)鏡像。實(shí)際使用中這個(gè)地址的下載速度和穩(wěn)定性比默認(rèn)倉庫可靠得多。類似的公共鏡像還有幾個(gè)比如騰訊云、華為云的Maven倉庫配置方式完全一樣只需要換一下url。如果某個(gè)鏡像不穩(wěn)定換一個(gè)就行。4.4 鏡像配置的兩個(gè)小細(xì)節(jié)不少人在這一步栽過跟頭。配置鏡像后下載速度確實(shí)快了但有些項(xiàng)目里有特殊依賴來自某個(gè)私有倉庫。如果mirrorOf寫的是*那所有倉庫的請求都會被鏡像劫持私有倉庫里的依賴反而拉不下來了。我的習(xí)慣是鏡像只覆蓋中央倉庫即mirrorOf寫成central。如果項(xiàng)目里確實(shí)需要額外倉庫再單獨(dú)在pom.xml里配置倉庫地址這樣各司其職。另一個(gè)細(xì)節(jié)是修改settings.xml后需要重啟IDE才會生效否則IDE里用的還是舊配置。5. 跑通第一個(gè)構(gòu)建核心命令與一個(gè)能用的pom.xml5.1 最小pom.xml長這樣環(huán)境配好、鏡像配好之后該實(shí)際跑一個(gè)項(xiàng)目了。不管你現(xiàn)在用的IDE是什么第一步都可以先建一個(gè)純命令行的Maven項(xiàng)目來驗(yàn)證整條鏈路。在任意目錄下新建一個(gè)pom.xml文件內(nèi)容可以非常精簡project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIddemo-maven/artifactId version1.0-SNAPSHOT/version packagingjar/packaging properties maven.compiler.source17/maven.compiler.source maven.compiler.target17/maven.compiler.target project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties /projectgroupId、artifactId、version這三個(gè)坐標(biāo)共同決定了一個(gè)Maven項(xiàng)目的身份。source和target兩個(gè)屬性分別表示源碼的Java版本和編譯后class文件的版本如果你的JDK是11就寫11是8就寫8別直接照抄17。5.2 從clean到install完整命令順序在pom.xml所在目錄打開命令行按順序執(zhí)行下面幾條命令mvn clean compile mvn test mvn package mvn install這里簡單說明每一條的作用。mvn clean是清理target目錄把之前的編譯產(chǎn)物刪掉避免殘留文件影響新的構(gòu)建。mvn compile編譯主代碼到target/classes。mvn test執(zhí)行src/test/java下的單元測試。mvn package把項(xiàng)目按照pom.xml中packaging指定的方式打包成jar或war文件生成在target目錄下。mvn install會把打包產(chǎn)物安裝到本地倉庫。這部分很多初學(xué)者不理解為什么要install因?yàn)橥粋€(gè)機(jī)器上有多個(gè)項(xiàng)目互相依賴時(shí)A項(xiàng)目想用B項(xiàng)目的jar包B項(xiàng)目必須先install到本地倉庫A項(xiàng)目才能以依賴方式引用。5.3 三個(gè)特別容易混的命令命令作用影響范圍package打包但不安裝只生成target下的產(chǎn)物install打包并安裝到本地倉庫本機(jī)其他項(xiàng)目可用deploy打包并上傳到遠(yuǎn)程倉庫團(tuán)隊(duì)協(xié)作時(shí)使用實(shí)際開發(fā)中clean經(jīng)常和后面命令連用最常見的是mvn clean install。我看到很多人只執(zhí)行package然后在別的項(xiàng)目里引用時(shí)發(fā)現(xiàn)找不到依賴就是沒搞清楚install和package的區(qū)別。5.4 IDE里配置Maven用自己裝的別用自帶的如果你用的是常見Java IDE比如IDEA打開項(xiàng)目后IDE默認(rèn)會使用它自帶的Maven。這個(gè)自帶版本通常沒問題但會有兩個(gè)隱患一是自帶Maven的settings.xml可能不是你自己配置的鏡像下載依然慢二是升級IDE后Maven行為可能變化。建議手動(dòng)把IDE里的Maven指向自己安裝的版本。以IDEA為例進(jìn)入 Settings - Build, Execution, Deployment - Build Tools - Maven依次設(shè)置Maven home path選到你的Maven解壓目錄User settings file勾選Override并選擇你的settings.xml路徑Local repository如果配置的是D:\maven-repo這里會自動(dòng)讀取設(shè)置完重啟項(xiàng)目讓IDE重新導(dǎo)入Maven配置。第一次導(dǎo)入會下載很多依賴只要鏡像配好了速度一般很快。6. 實(shí)戰(zhàn)中遇到的高頻問題與排查鏈路6.1 中文亂碼從環(huán)境變量到IDE的一整套解法Maven構(gòu)建日志里如果中文變成一堆問號或亂碼通常不是代碼問題而是默認(rèn)編碼不一致。先檢查pom.xml里是否設(shè)置了project.build.sourceEncodingUTF-8/project.build.sourceEncoding如果設(shè)置了還是亂碼再看命令行窗口的代碼頁。在Windows的cmd里執(zhí)行chcp 65001切換到UTF-8編碼。如果是IDE的控制臺在IDE的啟動(dòng)參數(shù)里加一行-Dfile.encodingUTF-8然后重啟IDE。通常這一套操作下來亂碼問題基本能解決。6.2 依賴下載失敗或卡住.lastUpdated文件是什么鏡像配好了但偶爾還是會遇到某個(gè)依賴下載失敗之后再執(zhí)行命令就一直卡在同一個(gè)jar包。此時(shí)本地倉庫對應(yīng)目錄下會出現(xiàn).lastUpdated后綴的文件這是Maven記錄下載失敗狀態(tài)的標(biāo)記文件。只要這個(gè)文件存在Maven就不會重新嘗試下載。清除方式很簡單在命令行執(zhí)行mvn -U clean compile其中-U參數(shù)強(qiáng)制檢查遠(yuǎn)程倉庫更新。更徹底的做法是手動(dòng)刪除本地倉庫中對應(yīng)目錄下的lastUpdated文件再重新構(gòu)建。我在項(xiàng)目里遇到過這種場景明明換了鏡像源某個(gè)快照版本依賴還是反復(fù)失敗后來發(fā)現(xiàn)是本地倉庫里的失敗記錄沒清理。6.3 依賴沖突用dependency:tree看依賴樹項(xiàng)目稍微變大就可能出現(xiàn)兩個(gè)依賴傳遞引入了同一個(gè)庫的不同版本?，F(xiàn)象很典型編譯正常運(yùn)行時(shí)報(bào)NoSuchMethodError或ClassNotFoundException。排查思路很簡單執(zhí)行mvn dependency:treeMaven會把整個(gè)依賴樹打印出來你很快能看到同一個(gè)groupId出現(xiàn)了多個(gè)版本。處理方式是在pom.xml中顯式聲明需要用到的版本或者對某個(gè)傳遞依賴做排除。dependency groupIdorg.example/groupId artifactIddemo-lib/artifactId version1.0.0/version exclusions exclusion groupIdorg.example/groupId artifactIdconflict-lib/artifactId /exclusion /exclusions /dependency6.4 新電腦裝Maven的個(gè)人習(xí)慣最后分享一點(diǎn)我自己的習(xí)慣。每次在一臺新Windows電腦上裝Maven我不會先急著執(zhí)行IDE里的項(xiàng)目而是先按下面這個(gè)順序走一遍第一用java -version和javac -version確認(rèn)JDK可用再執(zhí)行mvn -v看Maven是否識別到正確的Java環(huán)境。第二把settings.xml里的本地倉庫路徑和鏡像源先改好然后執(zhí)行一個(gè)最簡單的mvn help:system命令讓Maven自動(dòng)初始化本地倉庫并讀取配置。第三跑一個(gè)最簡單的pom.xml項(xiàng)目把clean、compile、package整條鏈路走通再打開IDE導(dǎo)入項(xiàng)目。這套流程每次都能幫我提前發(fā)現(xiàn)環(huán)境問題而不是等IDE里項(xiàng)目導(dǎo)入失敗后才開始排查。如果你是第一次在Windows下配置Maven建議也按這個(gè)順序來能少走很多彎路。