1. 項(xiàng)目概述為什么在Mac上搞定Maven是Java開(kāi)發(fā)的基石如果你在Mac上搞Java開(kāi)發(fā)遲早得和Maven打交道。這玩意兒不是什么高深莫測(cè)的黑科技但它就像你廚房里的燃?xì)庠睢獩](méi)有它你連口熱乎飯都吃不上。Maven本質(zhì)上是一個(gè)項(xiàng)目管理和構(gòu)建自動(dòng)化工具它幫你解決最頭疼的依賴管理問(wèn)題。想象一下你寫(xiě)個(gè)程序要用到幾十個(gè)別人寫(xiě)好的庫(kù)jar包每個(gè)庫(kù)又有自己的依賴手動(dòng)下載、管理版本、處理沖突那簡(jiǎn)直是噩夢(mèng)。Maven通過(guò)一個(gè)叫pom.xml的配置文件聲明你需要什么它就去中央倉(cāng)庫(kù)幫你自動(dòng)下載、組裝保證版本正確構(gòu)建過(guò)程標(biāo)準(zhǔn)化。在Mac上配置Maven核心就兩步一是把Maven軟件包弄到你的電腦里安裝二是告訴你的系統(tǒng)“Maven”這個(gè)命令在哪里讓終端能找得到它配置環(huán)境變量。聽(tīng)起來(lái)簡(jiǎn)單但新手常在這里栽跟頭環(huán)境變量沒(méi)配對(duì)導(dǎo)致mvn -v命令報(bào)“command not found”或者下載的版本和JDK不兼容再或者本地倉(cāng)庫(kù)路徑亂設(shè)把系統(tǒng)盤(pán)塞滿。網(wǎng)上教程很多但要么太老要么跳步缺了“為什么這么做”的解釋照抄容易出問(wèn)題。這篇內(nèi)容就是帶你走一遍完整流程不僅告訴你每一步怎么操作更解釋清楚背后的邏輯讓你下次遇到類似問(wèn)題比如配置其他環(huán)境變量也能舉一反三。2. 核心準(zhǔn)備JDK與安裝包的選擇邏輯在安裝Maven之前有個(gè)硬性前提你的Mac上必須已經(jīng)安裝了Java Development Kit (JDK)。因?yàn)镸aven本身是用Java寫(xiě)的運(yùn)行它需要一個(gè)Java運(yùn)行時(shí)環(huán)境。這不是建議是必須。2.1 確認(rèn)與安裝JDK打開(kāi)你的終端Terminal輸入以下命令java -version如果能看到類似“java version “1.8.0_381””或“openjdk version “17.0.10””的輸出并且版本號(hào)大于等于1.7那么恭喜JDK已經(jīng)就緒。Maven 3.3 要求 JDK 1.7 或以上。如果顯示“No Java runtime present, requesting install.”或者版本太舊你就需要安裝或更新JDK。對(duì)于Mac用戶最省心的方式是去Oracle官網(wǎng)或直接使用OpenJDK。我個(gè)人推薦通過(guò)Homebrew安裝OpenJDK管理起來(lái)更方便如果你還沒(méi)安裝Homebrew先訪問(wèn) brew.sh 安裝這個(gè)包管理器。在終端里執(zhí)行brew install openjdk。默認(rèn)會(huì)安裝最新版本。如果你想安裝特定版本比如JDK 11可以用brew install openjdk11。安裝后brew會(huì)提示你如何將JDK添加到PATH。通常需要執(zhí)行類似sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk的命令并配置環(huán)境變量。請(qǐng)務(wù)必仔細(xì)閱讀安裝完成后的終端提示信息。注意不推薦從蘋(píng)果舊系統(tǒng)遺留的“Java偏好設(shè)置”面板安裝它提供的往往是較舊的JRE運(yùn)行環(huán)境而非完整的JDK開(kāi)發(fā)工具包可能缺少M(fèi)aven需要的工具。2.2 下載正確的Maven安裝包接下來(lái)是獲取Maven。請(qǐng)始終前往Apache Maven官網(wǎng)下載。這是唯一推薦的源安全、可靠、版本最新。在下載頁(yè)面你會(huì)看到兩種格式Binary zip archive和Source zip archive。你必須選擇Binary zip archive。這是編譯好的可執(zhí)行文件解壓就能用。Source zip archive是源代碼你需要自己編譯完全沒(méi)必要自找麻煩。關(guān)于版本選擇除非項(xiàng)目有歷史遺留要求否則直接下載最新的穩(wěn)定版Stable Release。最新版本修復(fù)了舊版的bug性能更好對(duì)新JDK兼容性也更佳。不用擔(dān)心“最新版不穩(wěn)定”Apache對(duì)穩(wěn)定版的發(fā)布有嚴(yán)格把控。下載下來(lái)的文件通常是apache-maven-3.9.6-bin.zip這種格式版本號(hào)會(huì)變。記住它下載到了哪里通常是“下載”文件夾。3. 安裝與配置的詳細(xì)步驟與原理剖析安裝的本質(zhì)就是把下載的壓縮包解壓到一個(gè)你希望永久存放它的目錄然后通過(guò)環(huán)境變量讓系統(tǒng)知道它的位置。3.1 解壓與安置選個(gè)好“家”不建議把Maven就扔在“下載”文件夾里也不建議直接解壓到桌面。這些地方文件容易被誤刪或移動(dòng)。我們應(yīng)該把它放到一個(gè)專為程序準(zhǔn)備的目錄。Mac系統(tǒng)有一個(gè)慣例位置/usr/local。這個(gè)目錄就是用來(lái)存放用戶自行安裝的軟件的。我們就把Maven放在這里。打開(kāi)“訪達(dá)”Finder使用快捷鍵Command Shift G在彈出的窗口中輸入/usr/local然后前往。如果你發(fā)現(xiàn)沒(méi)有權(quán)限直接在此文件夾內(nèi)操作或者想更清晰地管理也可以在自己用戶目錄下創(chuàng)建一個(gè)Applications或DevTools文件夾。這里我們以/usr/local為例進(jìn)行標(biāo)準(zhǔn)化操作。打開(kāi)終端使用解壓命令。假設(shè)你的zip文件在“下載”目錄終端命令如下# 切換到下載目錄 cd ~/Downloads # 解壓到 /usr/local 目錄 sudo unzip apache-maven-3.9.6-bin.zip -d /usr/local/這里使用了sudo是因?yàn)橄?usr/local寫(xiě)入文件需要管理員權(quán)限系統(tǒng)會(huì)提示你輸入密碼。輸入時(shí)密碼不可見(jiàn)輸完回車即可。解壓完成后進(jìn)入/usr/local目錄查看ls /usr/local/你應(yīng)該能看到一個(gè)名為apache-maven-3.9.6的文件夾。這個(gè)文件夾就是Maven的全部。實(shí)操心得使用sudo時(shí)要小心確保命令拼寫(xiě)正確。-d參數(shù)是指定解壓目標(biāo)目錄非常方便避免了先解壓再移動(dòng)的兩步操作。3.2 配置環(huán)境變量讓終端認(rèn)識(shí)mvn命令現(xiàn)在Maven已經(jīng)躺在你的硬盤(pán)里了但你在終端輸入mvn系統(tǒng)還是會(huì)說(shuō)“不認(rèn)識(shí)”。因?yàn)橄到y(tǒng)不知道去哪個(gè)文件夾找這個(gè)叫mvn的可執(zhí)行文件。環(huán)境變量PATH的作用就是告訴系統(tǒng)當(dāng)我在終端輸入一個(gè)命令時(shí)你應(yīng)該去哪些目錄里尋找這個(gè)命令對(duì)應(yīng)的程序。我們需要把Maven的bin目錄/usr/local/apache-maven-3.9.6/bin添加到PATH變量中。Mac系統(tǒng)常用的Shell是zshCatalina及以后版本默認(rèn)或bash較老版本。它們的配置文件不同zsh: 配置文件是~/.zshrc~代表你的用戶主目錄bash: 配置文件是~/.bash_profile或~/.bashrc如何知道自己在用哪個(gè)在終端輸入echo $SHELL輸出/bin/zsh就是zsh/bin/bash就是bash。我們以當(dāng)前主流的zsh為例使用文本編輯器打開(kāi)配置文件。用系統(tǒng)自帶的nano編輯器最直接nano ~/.zshrc在文件的末尾不要?jiǎng)悠渌麅?nèi)容添加以下幾行# Maven Environment Variables export MAVEN_HOME/usr/local/apache-maven-3.9.6 export PATH$MAVEN_HOME/bin:$PATH第一行設(shè)置了一個(gè)新的環(huán)境變量MAVEN_HOME它的值就是你的Maven安裝目錄。這是一個(gè)約定俗成的做法很多Java相關(guān)的工具會(huì)檢查這個(gè)變量。第二行這是關(guān)鍵。PATH$MAVEN_HOME/bin:$PATH的意思是新的PATH變量由兩部分組成$MAVEN_HOME/bin即Maven的命令目錄和原來(lái)的$PATH中間用冒號(hào):分隔。把$MAVEN_HOME/bin放在前面意味著系統(tǒng)會(huì)優(yōu)先在這個(gè)目錄里查找命令。編輯完成后按Control X退出按Y確認(rèn)保存再按回車確認(rèn)文件名。讓配置立刻生效剛剛修改的只是文件需要讓當(dāng)前的終端會(huì)話重新加載這個(gè)配置。source ~/.zshrc這條命令會(huì)執(zhí)行.zshrc文件中的所有設(shè)置。如果你是bash用戶操作完全類似只是把.zshrc換成.bash_profile然后執(zhí)行source ~/.bash_profile。3.3 驗(yàn)證安裝看到版本號(hào)才算成功現(xiàn)在在終端輸入驗(yàn)證命令mvn -v或者mvn --version如果配置正確你會(huì)看到類似下面的輸出Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae) Maven home: /usr/local/apache-maven-3.9.6 Java version: 17.0.10, vendor: Homebrew, runtime: /opt/homebrew/Cellar/openjdk/17.0.10/libexec/openjdk.jdk/Contents/Home ...這清晰地顯示了Maven版本、安裝路徑以及它使用的Java版本。看到這個(gè)就說(shuō)明Maven安裝和環(huán)境變量配置完全成功了。注意事項(xiàng)如果提示“command not found: mvn”99%是環(huán)境變量配置有問(wèn)題。請(qǐng)按以下步驟排查1. 檢查MAVEN_HOME的路徑是否完全正確多一個(gè)空格或少一個(gè)斜杠都不行。2. 檢查PATH的拼寫(xiě)。3. 確認(rèn)你修改的是正確的配置文件zsh還是bash。4. 執(zhí)行source命令了嗎5. 可以新開(kāi)一個(gè)終端窗口試試因?yàn)樾麓翱跁?huì)重新加載配置。4. 深入配置本地倉(cāng)庫(kù)與鏡像加速安裝和基礎(chǔ)配置只是讓你能用Maven。要想用得順手、飛快還需要進(jìn)行兩項(xiàng)關(guān)鍵配置設(shè)置本地倉(cāng)庫(kù)位置和配置國(guó)內(nèi)鏡像源。4.1 理解與配置本地倉(cāng)庫(kù)Maven有一個(gè)核心概念倉(cāng)庫(kù)。分為遠(yuǎn)程倉(cāng)庫(kù)中央倉(cāng)庫(kù)和本地倉(cāng)庫(kù)。當(dāng)你項(xiàng)目pom.xml里聲明了一個(gè)依賴Maven會(huì)首先去本地倉(cāng)庫(kù)找如果找到了就直接使用如果沒(méi)找到才去遠(yuǎn)程倉(cāng)庫(kù)下載并緩存到你的本地倉(cāng)庫(kù)。這個(gè)本地倉(cāng)庫(kù)默認(rèn)位置在~/.m2/repository~是你的用戶主目錄。為什么需要改默認(rèn)的C盤(pán)用戶目錄空間寶貴而本地倉(cāng)庫(kù)會(huì)隨著時(shí)間推移變得非常龐大幾個(gè)G到幾十個(gè)G都很常見(jiàn)可能擠占系統(tǒng)盤(pán)空間。把它挪到一個(gè)空間更大的磁盤(pán)分區(qū)是明智之舉。如何修改我們需要修改Maven的全局配置文件$MAVEN_HOME/conf/settings.xml。這個(gè)文件控制所有使用該Maven的項(xiàng)目的全局行為。在終端中用nano或你喜歡的編輯器如VSCode打開(kāi)這個(gè)文件sudo nano /usr/local/apache-maven-3.9.6/conf/settings.xml同樣需要sudo因?yàn)?usr/local下的文件通常需要權(quán)限在這個(gè)XML文件中找到localRepository這個(gè)注釋掉的配置項(xiàng)大約在53行左右。它默認(rèn)是這樣的!-- localRepository | The path to the local repository maven will use to store artifacts. | | Default: ${user.home}/.m2/repository localRepository/path/to/local/repo/localRepository --我們需要取消注釋并修改它。將下面這行!--localRepository/path/to/local/repo/localRepository--修改為例如我想把倉(cāng)庫(kù)放在我的數(shù)據(jù)盤(pán)/Volumes/Data下的一個(gè)文件夾localRepository/Volumes/Data/maven_repository/localRepository提示路徑你可以自由指定但請(qǐng)確保a) 該路徑存在不存在就提前用mkdir創(chuàng)建好b) 你有該路徑的讀寫(xiě)權(quán)限c) 路徑中不要包含中文或特殊字符避免潛在問(wèn)題。4.2 配置國(guó)內(nèi)鏡像源下載速度飛起Maven中央倉(cāng)庫(kù)服務(wù)器在國(guó)外國(guó)內(nèi)直接訪問(wèn)速度可能很慢甚至超時(shí)。解決方法是使用國(guó)內(nèi)大廠提供的鏡像倉(cāng)庫(kù)它們會(huì)從中央倉(cāng)庫(kù)同步資源國(guó)內(nèi)訪問(wèn)速度極快。最常用的是阿里云Maven鏡像。同樣在settings.xml文件中配置。在settings.xml中找到mirrors標(biāo)簽部分。在mirrors標(biāo)簽內(nèi)部添加如下mirror配置mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共倉(cāng)庫(kù)/name urlhttps://maven.aliyun.com/repository/public/url /mirrorid: 鏡像的唯一標(biāo)識(shí)可以自定義。mirrorOf:*表示匹配所有遠(yuǎn)程倉(cāng)庫(kù)即任何對(duì)于中央倉(cāng)庫(kù)等遠(yuǎn)程倉(cāng)庫(kù)的請(qǐng)求都會(huì)轉(zhuǎn)到這個(gè)鏡像。你也可以指定具體的倉(cāng)庫(kù)id。name: 描述名稱。url: 阿里云鏡像倉(cāng)庫(kù)的地址。配置完成后保存并關(guān)閉settings.xml。從此以后所有依賴下載都會(huì)走阿里云鏡像速度會(huì)有質(zhì)的提升。實(shí)操心得修改settings.xml后對(duì)已經(jīng)打開(kāi)的項(xiàng)目或終端可能不會(huì)立即生效。最穩(wěn)妥的方法是關(guān)閉IDE如IntelliJ IDEA和所有終端窗口再重新打開(kāi)。IDEA通常會(huì)在檢測(cè)到Maven配置變化時(shí)提示你重新導(dǎo)入項(xiàng)目。5. 在IDE中集成Maven以IntelliJ IDEA為例在終端里能用mvn命令不代表你的開(kāi)發(fā)工具IDE也能用。我們還需要在IDE里告訴它“嘿我用的是我自己安裝的這個(gè)Maven不是IDE自帶的那個(gè)。”為什么不用IDE自帶的自帶的Maven版本可能較舊且配置如settings.xml是獨(dú)立的不方便統(tǒng)一管理。使用我們自己配置的可以確保團(tuán)隊(duì)所有成員、所有項(xiàng)目構(gòu)建環(huán)境一致。在IntelliJ IDEA中配置的步驟打開(kāi)IntelliJ IDEA進(jìn)入偏好設(shè)置Preferences。可以通過(guò)菜單欄IntelliJ IDEA - Preferences或使用快捷鍵Command ,。在設(shè)置窗口導(dǎo)航到Build, Execution, Deployment - Build Tools - Maven。你會(huì)看到幾個(gè)關(guān)鍵配置項(xiàng)Maven home path: 這里就是選擇Maven的安裝目錄。點(diǎn)擊下拉框或后面的文件夾圖標(biāo)選擇我們之前安裝的路徑/usr/local/apache-maven-3.9.6。IDEA會(huì)自動(dòng)識(shí)別。User settings file: 這是用戶級(jí)別的settings.xml文件路徑。通常我們使用Maven安裝目錄下conf里的那個(gè)全局設(shè)置。確保它指向/usr/local/apache-maven-3.9.6/conf/settings.xml。旁邊的Override復(fù)選框可以勾選以明確指定。Local repository: 這個(gè)路徑會(huì)自動(dòng)讀取你上面settings.xml里配置的localRepository值。如果這里顯示的是你修改后的大容量磁盤(pán)路徑就說(shuō)明配置生效了。點(diǎn)擊Apply然后OK。現(xiàn)在當(dāng)你在IDEA中打開(kāi)或?qū)胍粋€(gè)Maven項(xiàng)目pom.xml文件IDEA就會(huì)使用你配置的Maven、你的鏡像源和你的本地倉(cāng)庫(kù)來(lái)下載依賴和運(yùn)行構(gòu)建命令如clean,compile,package。注意事項(xiàng)有時(shí)在IDEA中執(zhí)行Maven命令比如點(diǎn)界面上的“Maven”工具窗口里的生命周期時(shí)下載的依賴包沒(méi)有出現(xiàn)在你指定的本地倉(cāng)庫(kù)而是還在默認(rèn)的~/.m2/repository。這大概率是因?yàn)槟氵@個(gè)特定項(xiàng)目的.idea工作區(qū)配置或項(xiàng)目自身的.mvn配置覆蓋了全局設(shè)置。檢查一下項(xiàng)目根目錄下是否有.mvn文件夾里面可能有覆蓋配置。或者在IDEA的Maven工具窗口里檢查當(dāng)前生效的settings.xml文件路徑是否正確。6. 常見(jiàn)問(wèn)題排查與實(shí)戰(zhàn)技巧即使按照步驟操作也可能會(huì)遇到一些坑。這里記錄幾個(gè)最常見(jiàn)的問(wèn)題和解決方法。6.1 環(huán)境變量配置后命令仍找不到癥狀在終端輸入mvn -v提示 “zsh: command not found: mvn”。排查思路檢查路徑首先echo $MAVEN_HOME看輸出是不是/usr/local/apache-maven-3.9.6。如果不是說(shuō)明變量沒(méi)設(shè)對(duì)回去檢查.zshrc文件。檢查PATHecho $PATH查看輸出的長(zhǎng)長(zhǎng)一串路徑中是否包含$MAVEN_HOME/bin或具體的/usr/local/apache-maven-3.9.6/bin。如果沒(méi)有說(shuō)明PATH添加失敗。配置文件生效了嗎確保你執(zhí)行了source ~/.zshrc。或者最簡(jiǎn)單的方法完全關(guān)閉當(dāng)前終端窗口重新打開(kāi)一個(gè)新的終端窗口再試。新終端會(huì)自動(dòng)加載最新的配置文件。拼寫(xiě)錯(cuò)誤仔細(xì)檢查.zshrc里有沒(méi)有拼寫(xiě)錯(cuò)誤比如MAVEN_HMOEPAHT等。文件權(quán)限極少數(shù)情況檢查一下Maven的bin目錄下的mvn腳本是否有可執(zhí)行權(quán)限ls -l /usr/local/apache-maven-3.9.6/bin/mvn。應(yīng)該有x權(quán)限。6.2 依賴下載失敗或速度極慢癥狀在IDEA或終端執(zhí)行mvn compile時(shí)卡在下載某個(gè)依賴最后報(bào)超時(shí)錯(cuò)誤。解決方案確認(rèn)鏡像配置首先確認(rèn)你的settings.xml里的阿里云鏡像配置正確無(wú)誤且沒(méi)有被注釋掉。清理本地錯(cuò)誤緩存有時(shí)某個(gè)依賴下載不完整會(huì)導(dǎo)致后續(xù)一直失敗。可以到本地倉(cāng)庫(kù)目錄你配置的那個(gè)路徑找到對(duì)應(yīng)失敗依賴的文件夾直接整個(gè)刪除。然后讓Maven重新下載。檢查網(wǎng)絡(luò)代理如果你在公司網(wǎng)絡(luò)或使用了網(wǎng)絡(luò)代理可能需要為Maven配置代理。在settings.xml中找到proxies部分進(jìn)行配置。不過(guò)對(duì)于大多數(shù)使用阿里云鏡像的家庭網(wǎng)絡(luò)不需要代理。使用-U參數(shù)強(qiáng)制更新在命令后加-U如mvn clean compile -U這會(huì)強(qiáng)制Maven檢查所有遠(yuǎn)程倉(cāng)庫(kù)的更新有時(shí)能解決一些緩存導(dǎo)致的元數(shù)據(jù)問(wèn)題。6.3 IDEA中Maven項(xiàng)目依賴報(bào)紅或無(wú)法解析癥狀I(lǐng)DEA項(xiàng)目里pom.xml文件中的依賴標(biāo)簽變紅或者外部庫(kù)顯示找不到。解決步驟重新導(dǎo)入項(xiàng)目在IDEA右側(cè)的“Maven”工具窗口中點(diǎn)擊那個(gè)刷新的圖標(biāo)Reimport All Maven Projects。這是最常用、最有效的操作。檢查Maven配置如第5部分所述確認(rèn)IDEA中設(shè)置的Maven home、settings file是否正確指向了你配置好的那一套。離線模式檢查確保沒(méi)有意外勾選“離線模式”O(jiān)ffline Mode。在Maven工具窗口的頂部有這樣一個(gè)切換按鈕。清理并重新生成在終端進(jìn)入項(xiàng)目根目錄執(zhí)行mvn clean compile -DskipTests。如果終端能成功通常IDEA同步一下也會(huì)好。檢查JDK版本確保IDEA中為該項(xiàng)目設(shè)置的Project SDK與pom.xml中指定的maven.compiler.source和maven.compiler.target版本兼容。6.4 權(quán)限問(wèn)題Permission Denied癥狀在執(zhí)行Maven命令或IDEA構(gòu)建時(shí)出現(xiàn)“Permission denied”錯(cuò)誤尤其是在向/usr/local目錄寫(xiě)入或從倉(cāng)庫(kù)下載時(shí)。根本原因Mac系統(tǒng)的權(quán)限管理SIP和文件權(quán)限比較嚴(yán)格。解決方法對(duì)于安裝目錄/usr/local/apache-maven-3.9.6確保當(dāng)前用戶有讀取和執(zhí)行權(quán)限。通常用sudo解壓進(jìn)去的權(quán)限是對(duì)的。對(duì)于本地倉(cāng)庫(kù)目錄這是最常出問(wèn)題的地方。如果你把本地倉(cāng)庫(kù)設(shè)在了非用戶主目錄下的位置比如/Volumes/Data/maven_repository你需要確保當(dāng)前用戶對(duì)這個(gè)目錄有完全的讀寫(xiě)權(quán)限。可以在終端執(zhí)行sudo chown -R $(whoami) /Volumes/Data/maven_repository這條命令將目錄的所有者改為當(dāng)前用戶。-R是遞歸處理目錄內(nèi)所有文件。我個(gè)人在配置完所有環(huán)境后習(xí)慣做一個(gè)簡(jiǎn)單的驗(yàn)證流程關(guān)閉所有終端和IDE新開(kāi)一個(gè)終端運(yùn)行mvn -v和java -version確認(rèn)基礎(chǔ)環(huán)境然后用一個(gè)最簡(jiǎn)單的pom.xml可以從網(wǎng)上找一個(gè)Hello World的Maven項(xiàng)目進(jìn)行mvn clean compile觀察依賴下載和構(gòu)建過(guò)程是否順暢。這個(gè)流程能一次性驗(yàn)證JDK、Maven安裝、環(huán)境變量、鏡像配置、本地倉(cāng)庫(kù)權(quán)限等多個(gè)環(huán)節(jié)確保你的Maven環(huán)境是真正可用的。