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