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