在Windows上裝Maven大概是很多Java開發(fā)者入門時遇到的第一道“假門檻”。說它假是因為步驟翻來覆去就那么幾招下載解壓、配環(huán)境變量、改一下settings.xml。說它是門檻是因為其中任何一步走偏后面就會冒出一連串莫名其妙的問題——不是報“mvn 不是內(nèi)部或外部命令”就是依賴下載到一半直接卡死甚至配置好了IDEA仍然視而不見。這些年我?guī)筒簧傩氯伺挪檫^環(huán)境看到最多的狀態(tài)是“照著教程做完了但還是跑不起來”問題大多出在版本選擇和環(huán)境變量細節(jié)上。這篇就把Windows版Maven從安裝到配置的完整鏈路講清楚尤其把那些容易踩的坑單獨拎出來說。1. Windows下裝Maven為什么容易栽在環(huán)境變量上1.1 先分清安裝方式官方壓縮包、包管理器還是IDE內(nèi)置Maven在Windows上并沒有一個像樣的“安裝程序”最常見的方式是下載Apache官方提供的zip壓縮包解壓后直接使用。很多人會拿Chocolatey、Scoop這類包管理器去裝命令確實簡單比如choco install maven裝完后整個環(huán)境可能被放到一個帶版本號的目錄里后續(xù)升級和管理仍然要走包管理器那條線。但我的建議是用官方二進制zip。原因很直接——作為構(gòu)建工具Maven本身就只是一個帶bin腳本和lib庫的目錄它的“安裝”本質(zhì)上是把目錄放對位置、把環(huán)境變量指對它。用zip包的方式你對目錄結(jié)構(gòu)有完全的控制權(quán)出問題時也更容易定位。另外有不少人以為IDEA自帶了Maven就不用裝了。這個想法部分正確但最好別這么干。IDEA內(nèi)置的Maven版本往往跟著IDE走你無法精確控制它用的到底是3.8還是3.9而且你以后在命令行里使用Maven時依然需要一個獨立安裝的版本。所以無論你用不用IDE都建議在本機裝一套獨立Maven。1.2 版本選擇3.9.x是目前最穩(wěn)妥的Windows選擇打開Maven官網(wǎng)下載頁會看到一長串版本號和壓縮包。很多新手會直接點最新版但這里我要多說一句Maven 4目前還處于RC階段不建議在正式環(huán)境里使用如果你在2025年之后看到4.x正式發(fā)布那可以等社區(qū)穩(wěn)定一段時間再升。當前最穩(wěn)妥的是3.9.x系列它對JDK 8和更高版本都支持得很好插件兼容性也經(jīng)過了很長時間的驗證。這里還牽扯到一個基礎(chǔ)前提Maven本身需要JDK而不是JRE。因為Maven啟動時就要調(diào)用Java編譯器相關(guān)API只用JRE運行會直接報錯。所以你安裝Maven之前必須先把JDK裝好并設(shè)置好JAVA_HOME。JDK版本方面Maven 3.9.x官方要求JDK 8以上我這邊同時用過JDK 11、17和21都很正常。需要注意的是如果你本地裝了多個JDK那么JAVA_HOME指向哪個JDKMaven實際用的就是哪個。后面配置的時候要特別注意。1.3 用戶變量和系統(tǒng)變量到底配哪一個Windows環(huán)境變量分兩類用戶變量和系統(tǒng)變量。用戶變量只對當前Windows賬戶生效系統(tǒng)變量則對所有賬戶生效并且修改系統(tǒng)變量需要管理員權(quán)限。很多教程讓你在“系統(tǒng)變量”里新建MAVEN_HOME這本身沒錯但如果你只是為了自己開發(fā)用完全沒必要碰系統(tǒng)變量。尤其是多人共用一臺電腦的場景你改了系統(tǒng)變量別人也可能被影響。更麻煩的是有的公司電腦被安全策略鎖定非管理員用戶在系統(tǒng)變量里什么都寫不進去。我個人習慣是配置在用戶變量里然后把%MAVEN_HOME%\bin加到用戶PATH中。這樣既不需要管理員權(quán)限又干凈隔離。后面所有命令在當前用戶下都能直接用。如果你用PowerShell設(shè)置用戶變量可以直接這樣setx MAVEN_HOME D:\dev\apache-maven-3.9.9 setx PATH $env:PATH;%MAVEN_HOME%\bin但要注意setx對PATH變量的操作有個坑它會把原有PATH讀出來再拼接如果原有PATH太長Windows對PATH長度有限制可能會被截斷。所以更推薦通過“系統(tǒng)屬性 - 環(huán)境變量”這個圖形界面來改相對安全。2. 下載版本和解壓目錄裝之前就要想清楚的事2.1 從Apache官網(wǎng)下載binary zip而不是源碼包Maven官網(wǎng)的下載區(qū)一般會提供兩種壓縮包一種是apache-maven-3.9.x-bin.zip另一種是apache-maven-3.9.x-src.zip。新手一定要選帶bin的那個src是源碼包解壓之后沒有可直接運行的bin\mvn.cmd拿它配環(huán)境變量只會得到一個“找不到命令”的下場。下載之前也順手看一下校驗值A(chǔ)pache官方會在下載頁旁邊列出SHA-512或SHA-256值。Windows下可以用PowerShell計算文件的哈希值Get-FileHash .\apache-maven-3.9.9-bin.zip -Algorithm SHA512如果算出來的值和官網(wǎng)對不上那這個文件很可能下載不完整解壓后運行時會報一些奇怪的Java類找不到錯誤。2.2 解壓目錄的命名和路徑比你想的更講究很多教程直接讓你解壓到C:\Program Files\apache-maven-3.9.9看起來沒問題但里面有空格如果某個工具在解析路徑時沒有正確處理引號就會出問題。雖然現(xiàn)代工具大多能處理空格但沒必要冒這個險。我推薦把Maven放到一個干凈、無空格、無中文的路徑下比如D:\dev\apache-maven-3.9.9。之前見過一個項目因為Maven路徑里帶了中文導致部分插件生成的文件路徑亂碼排查了很久才發(fā)現(xiàn)根因在環(huán)境變量路徑上。Windows對中文路徑的支持一直在改善但在跨平臺工具鏈里最好還是避免因為Maven會調(diào)用大量第三方插件它們對非ASCII路徑的處理水平參差不齊。解壓完成后先確認目錄結(jié)構(gòu)是不是對的。進入你的Maven目錄應該能看到這些內(nèi)容apache-maven-3.9.9\ ├─ bin\ │ ├─ mvn │ └─ mvn.cmd ├─ boot\ │ └─ plexus-classworlds-*.jar ├─ conf\ │ └─ settings.xml ├─ lib\ │ └─ (一堆jar包) └─ README.txt注意bin\mvn.cmd是Windows下真正執(zhí)行的文件bin\mvn是Shell腳本給Linux和macOS用的。如果解壓后bin目錄下沒有mvn.cmd大概率你下成了源碼包。2.3 不要把Maven安裝在項目目錄或U盤里有個反直覺的點Maven是開發(fā)工具不是項目依賴它不應該跟著某個項目走。有些人圖省事把Maven解壓到項目文件夾里結(jié)果換項目后又要重新配一遍。還有些人放在U盤里插拔之后路徑就變了環(huán)境變量里的配置跟著失效。正確做法是把它放在固定的開發(fā)工具目錄下比如D:\dev\或者用戶目錄下的Dev\tools\然后讓所有項目共用這一份。3. 環(huán)境變量配置的完整鏈路與驗證方法3.1 先確認JAVA_HOME指向的是JDK根目錄Maven啟動時會去找JAVA_HOME這個變量的值必須是JDK的安裝根目錄比如C:\Program Files\Java\jdk-17.0.11不能寫到bin目錄也不能指到JRE目錄。驗證 JAVA_HOME 是否正確的辦法是在PowerShell或CMD里執(zhí)行echo %JAVA_HOME%如果輸出為空或者指向一個不存在的路徑Maven運行時會報JAVA_HOME is set to an invalid directory。這個報錯信息非常典型我看到過的初學者環(huán)境問題里有三分之一都卡在這里。另外注意如果你用IDEA開發(fā)IDEA里也可以設(shè)置獨立的JVM作為“項目SDK”但那不影響命令行的Maven。命令行Maven只認Windows環(huán)境變量里的JAVA_HOME。所以裝完Maven后哪怕你在IDEA里點“刷新”點得再勤命令行環(huán)境不對照樣跑不起來。3.2 新建MAVEN_HOME并加入PATH圖形界面操作的路徑是“此電腦 - 屬性 - 高級系統(tǒng)設(shè)置 - 環(huán)境變量”。在“用戶變量”區(qū)域執(zhí)行下面兩步新建變量名MAVEN_HOME變量值為Maven解壓后的根目錄比如D:\dev\apache-maven-3.9.9。找到“用戶變量”里的Path雙擊打開點擊“新建”添加%MAVEN_HOME%\bin。之所以設(shè)置MAVEN_HOME而不是直接把完整路徑寫進PATH主要是為了以后升級方便。你以后從3.9.9換到3.9.10只需要改這一個變量值PATH不用動。如果直接把完整路徑D:\dev\apache-maven-3.9.9\bin寫進PATH將來升級后還得記得去改PATH那一長串時間一長就亂了。3.3 重新打開終端執(zhí)行mvn -v配置完環(huán)境變量后必須重新打開一個新的終端窗口因為Windows的終端窗口在啟動時會把環(huán)境變量讀入內(nèi)存老窗口里不會自動更新。新開一個PowerShell執(zhí)行mvn -v正常情況下輸出類似Apache Maven 3.9.9 (8e8019fd9c1c3c2d3c0f3c1a6e3d1f9a1a8) Maven home: D:\dev\apache-maven-3.9.9 Java version: 17.0.11, vendor: Eclipse Adoptium, runtime: C:\Program Files\Java\jdk-17.0.11 Default locale: zh_CN, platform encoding: UTF-8 OS name: windows 10, version: 10.0, arch: amd64, family: windows如果能看到類似信息說明基本鏈路已經(jīng)通了。不過這只是第一步真正容易出問題的是接下來的settings.xml和依賴下載環(huán)節(jié)。3.4 設(shè)置完環(huán)境變量后要不要重啟電腦很多教程會告訴你“配置完系統(tǒng)環(huán)境變量必須重啟電腦”這句話對但只適用于修改系統(tǒng)變量的情況。如果你配置的是用戶變量并且重新打開了終端窗口那么新配置已經(jīng)生效了不需要重啟。只有那些在配置環(huán)境變量的同時又開著很多后臺服務(wù)的情況才需要徹底注銷或重啟來確保所有進程都拿到最新變量。如果重新打開終端后mvn -v仍然報“不是內(nèi)部或外部命令”可以用下面命令快速排查當前到底用了哪個mvnwhere mvn如果找不到任何輸出說明PATH里沒有生效的Maven路徑如果輸出了一個路徑但不是你剛配置的那個說明系統(tǒng)里可能有其他版本的Maven被裝在別的位置并在PATH中排在前面。這類“命令被劫持”的情況在Windows上不算少見尤其是裝過一些軟件自帶的Maven之后。4. settings.xml才是Maven的“靈魂”本地倉庫與鏡像配置4.1 兩個settings.xml全局配置和用戶配置別搞混Maven有兩份settings.xml全局配置位于conf\settings.xml在Maven安裝目錄下。用戶配置位于C:\Users\你的用戶名\.m2\settings.xml默認并不存在需要自己創(chuàng)建。Maven在執(zhí)行時會先讀全局配置再讀用戶配置同一個節(jié)點如果兩邊都配置了用戶配置會覆蓋全局配置。所以最安全也最推薦的做法是不要隨意修改conf\settings.xml而是把自定義內(nèi)容寫到~\.m2\settings.xml。這樣即便以后Maven升級或換版本你的配置依然保留在用戶目錄里不會因為重新解壓一個新的Maven而丟失。4.2 localRepository放哪里才合適默認情況下Maven會把所有下載的依賴jar包放到C:\Users\你的用戶名\.m2\repository。這個位置有兩個潛在問題C盤空間壓力大。一個Java項目如果依賴多本地倉庫很快就能漲到幾個GBC盤本來就緊巴巴的話很容易爆。如果哪天需要重裝系統(tǒng)或遷移環(huán)境默認目錄不好找。我習慣的做法是把本地倉庫放到單獨的數(shù)據(jù)盤比如D:\maven-repo。settings.xml中這樣配置settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd localRepositoryD:/maven-repo/localRepository /settings注意這里的路徑分隔符我用了正斜杠/Maven在Windows下也接受這種方式能避免轉(zhuǎn)義符引發(fā)的奇怪問題。4.3 配置阿里云鏡像倉庫能省下大量下載時間Maven默認從Maven Central中央倉庫下載依賴這個倉庫服務(wù)器在國外。國內(nèi)網(wǎng)絡(luò)環(huán)境下直接下載的速度很不穩(wěn)定經(jīng)常出現(xiàn)幾百KB大的jar包都要下載半天甚至直接超時的情況。解決辦法是配置鏡像倉庫?，F(xiàn)在國內(nèi)比較常用的鏡像是阿里云的公共倉庫。在settings.xml里加一個mirror節(jié)點mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共倉庫/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors這里mirrorOf寫central表示僅僅把中央倉庫的請求鏡像到阿里云。如果你想把所有遠程倉庫請求都走阿里云可以寫成*但一般不推薦因為公司內(nèi)部私服倉庫如果也被鏡像掉會導致私服的依賴無法下載。所以精確寫成central是最穩(wěn)妥的。為什么官方文檔里我們有“鏡像”機制因為Maven下載依賴時會先查本地倉庫再查遠程倉庫。如果遠程倉庫配了鏡像Maven會直接去鏡像地址請求。阿里云這個倉庫實際上聚合了Maven中央倉庫、JCenter等來源對國內(nèi)開發(fā)者來說速度提升非常明顯。如果公司用的是私有倉庫比如Nexus也可以設(shè)置mirrorOf指向公司地址。優(yōu)先級順序是本地倉庫存在依賴 - 使用本地否則 - 走鏡像鏡像是通配還是精確匹配 - 決定最終訪問的倉庫地址。4.4 代理服務(wù)器和證書問題在公司網(wǎng)絡(luò)環(huán)境里HTTP下載經(jīng)常要走代理。如果命令行Maven一直下載失敗而瀏覽器訪問maven.aliyun.com又能正常打開那多半是代理沒配。settings.xml中可以直接配置代理proxies proxy idcompany-http-proxy/id activetrue/active protocolhttp/protocol hostproxy.company.com/host port8080/port username你的用戶名/username password你的密碼/password /proxy /proxies這里的用戶名密碼按需填如果沒有認證就能訪問代理可以省略這兩個節(jié)點。配置完成后Maven的wagon組件就會通過該代理下載依賴。證書問題更隱蔽。有些公司內(nèi)網(wǎng)環(huán)境會做HTTPS攔截導致Maven訪問遠程倉庫時報PKIX path building failed或SSLHandshakeException。遇到這種情況不要急著關(guān)閉SSL校驗正確做法是把公司根證書導入到JDK的cacerts里。一個典型的導入命令是keytool -import -trustcacerts -alias company-root-ca -file 公司根證書.cer -keystore %JAVA_HOME%\lib\security\cacerts -storepass changeit其中changeit是JDK默認keystore密碼如果你電腦上改過要換成自己設(shè)置的密碼。這樣做比直接給Maven加-Dmaven.wagon.http.ssl.insecuretrue安全得多至少不會把SSL校驗完全關(guān)掉。4.5 如何在配置后確認settings.xml是否生效配置完settings.xml后用下面的命令可以查看Maven實際讀到的生效配置mvn help:effective-settings執(zhí)行后會在控制臺里打印最終的合并配置。如果里面localRepository和mirror節(jié)點都正確顯示就說明你的配置沒有寫錯位置。如果顯示的還是默認路徑那大概率是擦到了另一個settings.xml或者XML文件里某個標簽寫錯了導致解析失敗。5. 在IDEA中接入Maven為什么IDE設(shè)置常會失效5.1 IDEA自帶的Maven和本地安裝的Maven不是一回事IDEA 在“Build Tools - Maven”里有一個“Maven home path”設(shè)置。默認情況下它用的是IDEA自帶的Maven路徑一般類似C:\Program Files\JetBrains\IntelliJ IDEA 2024.2\plugins\maven\lib\maven3。這個內(nèi)置版本雖然能用但你之前配置的settings.xml和本地倉庫路徑不一定被自動關(guān)聯(lián)。我建議在IDEA中手動指定剛才安裝的Maven路徑。以IntelliJ IDEA 2024版本為例操作路徑是File - Settings - Build, Execution, Deployment - Build Tools - Maven然后把“Maven home path”改成D:\dev\apache-maven-3.9.9。不要只改這一處。還要往下看有兩個關(guān)鍵字段User settings file改成C:\Users\你的用戶名\.m2\settings.xml。Local repository它會根據(jù)settings.xml里的localRepository自動讀取但如果沒自動變可以勾選“Override”手動指定為D:\maven-repo。這樣IDEA和命令行使用的就是同一套Maven配置不會再出現(xiàn)“命令行能編譯IDEA里依賴全紅”的靈異現(xiàn)象。5.2 導入項目后提示依賴找不到的排查順序很多時候項目的pom.xml沒有標紅但是Maven窗口里一堆依賴找不到。遇到這種情況我一般按這個順序排查首先打開IDEA右側(cè)的Maven工具窗口點擊最左上角的刷新按鈕強制重新導入。如果所有依賴還是紅的就看看界面右下角是不是提示了“Maven import failed”之類的信息點開詳細日志。其次檢查項目的JDK設(shè)置。點擊File - Project Structure - Project確保Project SDK是正確的JDK版本。如果項目用了JDK 17但你IDEA里的Project SDK還停留在JDK 8有些依賴會解析不到Maven編譯時還會報“不受支持的發(fā)行版本”錯誤。最后檢查IDEA Maven設(shè)置里的Runner選項。Runner - JRE要選擇項目所用JDK不要選“Use Project JDK”以外奇怪的選項。如果IDEA在導入時使用的是自定義JRE而不是JAVA_HOME指向的JDK也會出現(xiàn)Profile差異導致的奇怪問題。5.3 Runner中的VM options以項目為單位還是以Maven全局為單位IDEA里Maven Runner的VM options是全局生效的對每個通過IDEA執(zhí)行的Maven命令都會追加。常見的坑是有人在這里加了一堆內(nèi)存參數(shù)結(jié)果所有項目都受影響如果某個項目本身設(shè)置了大堆內(nèi)存兩者疊加可能導致啟動變慢甚至OOM。我個人的習慣是不在Runner里設(shè)置太多東西只在確實需要調(diào)試Maven插件時才臨時加一下比如加-Dmaven.wagon.http.connectionTimeout60000來延長下載超時時間。真正的環(huán)境級配置比如本地倉庫路徑和鏡像都應該放到settings.xml里而不是塞在IDEA VM options中。6. 敲mvn -v報錯時的排查實錄從環(huán)境變量到依賴下載6.1 “mvn 不是內(nèi)部或外部命令”的三個常見原因這個報錯基本等于“PATH里沒有找到mvn”。按照我踩過的坑原因往往集中在下面三個第一Maven的bin路徑?jīng)]寫進PATH或者寫成%MAVEN_HOME%而MAVEN_HOME本身沒配上。這個好解決回到系統(tǒng)屬性里重新檢查一遍。第二PATH中寫的是%MAVEN_HOME%\bin但MAVEN_HOME的值末尾多了一個斜杠比如D:\dev\apache-maven-3.9.9\這時%MAVEN_HOME%\bin會變成D:\dev\apache-maven-3.9.9\\binWindows雖然通常能容忍雙斜杠但個別命令還是會出問題。第三你安裝過其他工具比如某個開發(fā)套件自帶的Maven它的mvn.cmd被放在了另一個目錄且那個目錄在PATH中的排序比你的Maven更靠前。這種情況下你敲mvn -v執(zhí)行的是別人的Maven路徑自然不是你期望的。用where mvn查一下即可。6.2 依賴下載失敗與中央倉庫連接問題命令行執(zhí)行mvn clean package時卡在下載依賴最常見的現(xiàn)象是控制臺反復出現(xiàn)某個artifact下載失敗的日志最后提示Could not transfer artifact或Transfer failed。先別急著懷疑本地倉庫壞了大概率是網(wǎng)絡(luò)訪問遠程倉庫太慢。解決辦法就是剛才說的配置阿里云鏡像后再試。如果已經(jīng)配了鏡像還失敗檢查鏡像的url是否寫對尤其注意不要漏了https://前綴。如果公司內(nèi)網(wǎng)有Nexus私服你的settings.xml里可能同時有mirror和profile的repository配置。此時要看私服地址是否可達用瀏覽器直接訪問私服地址看能否打開能打開但Maven連不上那就是代理或證書問題走代理配置或?qū)胱C書方案。6.3 編譯時亂碼和編碼問題Windows上另一個高頻坑是編碼。Maven默認會把平臺編碼寫到構(gòu)建信息里如果你的系統(tǒng)區(qū)域設(shè)置是非UTF-8比如中文Windows默認使用GBK那么項目源碼里帶中文注釋或字符串時編譯輸出或打包后的文件可能亂碼。最好的辦法是在Maven的運行參數(shù)里強制指定UTF-8。在settings.xml里加一個profile是最干凈的路徑profiles profile idutf8/id activation activeByDefaulttrue/activeByDefault /activation properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding maven.compiler.encodingUTF-8/maven.compiler.encoding /properties /profile /profiles同時把IDEA的文件編碼也改成UTF-8File - Settings - Editor - File Encodings全部改為UTF-8并勾選“Transparent native-to-ascii conversion”。這樣能避免95%以上的中文亂碼問題。6.4 配置正確后第一次完整構(gòu)建驗證配置完成后建議新建一個最基礎(chǔ)的項目跑一遍別一上來就編譯大型項目。用Maven自帶的archetype快速創(chuàng)建項目mvn archetype:generate -DgroupIdcom.example -DartifactIddemo-project -DarchetypeArtifactIdmaven-archetype-quickstart -DinteractiveModefalse這里的-DinteractiveModefalse是為了跳過交互式選擇直接以默認參數(shù)生成。第一次執(zhí)行時Maven會下載大量插件耗時可能比較長如果看到下載進度持續(xù)在動說明鏡像配置生效。如果卡住不動CtrlC終止后重新檢查settings.xml。如果你不想生成新項目也可以直接對一個已有的pom.xml執(zhí)行mvn compile -U其中-U是強制更新快照版本。這個命令會檢查整個構(gòu)建鏈路是否通暢。6.5 一個容易被忽略的細節(jié)Windows路徑中的空格和特殊字符最后再提一個很多人忽略的細節(jié)Maven的本地倉庫路徑、項目路徑或者settings.xml里配置的路徑如果有空格某些第三方插件會莫名報錯。比如一個插件要執(zhí)行exec命令在Windows下對帶空格的路徑處理不嚴謹就會提示找不到文件。解決方案很簡單項目的全路徑中避免空格和中文本地倉庫目錄也放到一個簡單路徑下比如D:\maven-repo。這不是Maven本身的問題而是整個Java工具鏈在Windows下對路徑處理的通病。我個人在實際操作中最深的體會是Maven在Windows上并不是裝完就萬事大吉配置的完整閉環(huán)是“安裝目錄干凈 環(huán)境變量獨立 settings.xml自定義 IDE關(guān)聯(lián)同一套配置”。每次配完我都會先跑一次mvn -v再跑一次mvn help:effective-settings確認環(huán)境變量和配置都指向預期值后才開始建項目。Maven這種工具前期花十分鐘把基礎(chǔ)設(shè)施扎穩(wěn)后面省下的是幾十小時排查依賴和構(gòu)建問題的時間。