項(xiàng)目里配置其他的依賴庫(kù)卻總是下載失敗這句話如果你也在工位上喊過(guò)那這篇內(nèi)容就是給你準(zhǔn)備的。我最近接手的模擬項(xiàng)目X需要引入幾個(gè)第三方庫(kù)結(jié)果從早上到下午下載進(jìn)度條一直在原地打轉(zhuǎn)好不容易起了個(gè)頭又報(bào)“連接超時(shí)”或者“Checksum mismatch”。這個(gè)問(wèn)題說(shuō)大不大但卡住之后整個(gè)研發(fā)節(jié)奏全亂而且它不像業(yè)務(wù)Bug有明確堆棧依賴下載失敗往往是環(huán)境、網(wǎng)絡(luò)、緩存、版本策略一堆因素疊在一起。這篇文章不想只丟給你幾行命令而是想把一套排查思路徹底拆開(kāi)。我會(huì)從實(shí)際報(bào)錯(cuò)怎么讀、常見(jiàn)原因怎么定位再到 Maven、Gradle、npm、pip 這些主流工具怎么寫(xiě)配置最后整理成一張速查表。無(wú)論你是后端、前端還是做數(shù)據(jù)分析腳本只要被依賴下載卡過(guò)應(yīng)該都能在這里找到對(duì)應(yīng)的解法。1. 先判斷“下載失敗”到底是什么性質(zhì)的失敗1.1 報(bào)錯(cuò)信息里的三個(gè)關(guān)鍵層級(jí)依賴下載失敗的報(bào)錯(cuò)看起來(lái)都是一團(tuán)紅字但拆開(kāi)之后其實(shí)就三類網(wǎng)絡(luò)層、倉(cāng)庫(kù)層、本地環(huán)境層。網(wǎng)絡(luò)層常見(jiàn)的關(guān)鍵字有Connection timed out、Connection reset、UnknownHostException倉(cāng)庫(kù)層常見(jiàn)的是403 Forbidden、404 Not Found、Authentication failed、Checksum mismatch、Could not transfer artifact本地環(huán)境層會(huì)出現(xiàn)Permission denied、No space left on device這類系統(tǒng)級(jí)問(wèn)題。如果能在報(bào)錯(cuò)第一行就定位到屬于哪一類后面排查能省一半時(shí)間。這里有個(gè)特別容易犯的誤區(qū)只看最后一個(gè)錯(cuò)誤。例如 Maven 報(bào)錯(cuò)一大串最后一行是Could not resolve dependencies for project ...但真正的根因可能在上面幾行的Connection reset里。所以看到下載失敗第一件事不是去改版本號(hào)而是把完整日志拉到文本文件里從最上面的異常開(kāi)始看起。大部分構(gòu)建工具會(huì)把 “cause by” 鏈打出來(lái)順著異常鏈往根上找比盯著最后一行猜要高效得多。為了更直觀我做了一個(gè)簡(jiǎn)單的報(bào)錯(cuò)分類表報(bào)錯(cuò)層級(jí)典型關(guān)鍵字說(shuō)明網(wǎng)絡(luò)層Connection timed out / Connection reset / UnknownHost多為網(wǎng)絡(luò)連不通或連接被切斷倉(cāng)庫(kù)層403 / 404 / Checksum mismatch / Could not transfer倉(cāng)庫(kù)地址不對(duì)、權(quán)限不足或文件損壞本地環(huán)境層No space left on device / Permission denied本地磁盤(pán)滿、緩存目錄無(wú)權(quán)限這張表可以先截圖存著遇到報(bào)錯(cuò)先對(duì)號(hào)入座別上來(lái)就清緩存換版本。1.2 先做一次干凈的“最小復(fù)現(xiàn)”我在排查這類問(wèn)題的時(shí)候不會(huì)直接在完整項(xiàng)目里一遍遍構(gòu)建而是先用一個(gè)空目錄建一個(gè)最小工程只加一個(gè)依賴去下載。這樣能排除大量無(wú)關(guān)干擾比如項(xiàng)目里其他依賴的版本沖突、多模塊構(gòu)建順序、代碼編譯器版本等。這個(gè)最小復(fù)現(xiàn)工程不要用公司內(nèi)部代碼就用一個(gè)簡(jiǎn)單的示例庫(kù)坐標(biāo)com.example:demo-lib:1.0.0如果沒(méi)有就用項(xiàng)目里報(bào)錯(cuò)的那個(gè)依賴刪掉其他依賴單獨(dú)構(gòu)建。比如 Maven 項(xiàng)目可以開(kāi)一個(gè)空目錄寫(xiě)一個(gè)只有一個(gè)依賴的pom.xml然后執(zhí)行mvn dependency:get -Dartifactcom.example:demo-lib:1.0.0如果只下載一個(gè)依賴都失敗說(shuō)明問(wèn)題出在網(wǎng)絡(luò)、倉(cāng)庫(kù)或本地緩存跟業(yè)務(wù)代碼無(wú)關(guān)如果這個(gè)依賴能下載成功再把項(xiàng)目里的其他依賴逐個(gè)加入很快就能定位到是哪一步開(kāi)始失敗的。這個(gè)“逐層加依賴”的過(guò)程看似笨但它能精準(zhǔn)地把問(wèn)題隔離到某個(gè)具體坐標(biāo)上后續(xù)修復(fù)就有靶子了。記錄日志也很關(guān)鍵。我一般會(huì)把輸出同時(shí)保存一份mvn dependency:get -Dartifactcom.example:demo-lib:1.0.0 -X download-debug.log-X會(huì)輸出調(diào)試級(jí)別的日志雖然長(zhǎng)但里面會(huì)包含實(shí)際請(qǐng)求的倉(cāng)庫(kù)地址、走了哪個(gè)鏡像、用了多長(zhǎng)時(shí)間才超時(shí)等信息。這些信息平時(shí)看不見(jiàn)排查下載問(wèn)題的時(shí)候特別有用。前提是日志里如果包含私有倉(cāng)庫(kù)地址注意別隨手粘貼到公開(kāi)渠道防止信息外泄。1.3 看超時(shí)時(shí)間判斷是“慢”還是“死”如果報(bào)錯(cuò)里有Read timed out或connect timed out還要再看具體超時(shí)時(shí)間。默認(rèn)的超時(shí)時(shí)間可能很長(zhǎng)本地一個(gè)依賴幾十分鐘下不來(lái)最后才報(bào)錯(cuò)。這種情況看起來(lái)像“死掉”其實(shí)只是“慢”。我習(xí)慣在配置里把超時(shí)稍微調(diào)大但不建議調(diào)到無(wú)限大否則一個(gè)壞依賴會(huì)卡住整個(gè)構(gòu)建好幾個(gè)小時(shí)。更實(shí)用的是觀察下載速度如果下載到某個(gè) jar 包時(shí)速率一直在幾十 KB 徘徊大概率是倉(cāng)庫(kù)給的帶寬很緊張如果請(qǐng)求發(fā)出去立刻失敗那大概率是網(wǎng)絡(luò)鏈路不通。判斷完類型之后再往下找原因就清晰多了。下面我把常見(jiàn)原因挨個(gè)拆開(kāi)講。2. 依賴庫(kù)下載失敗的常見(jiàn)原因逐個(gè)拆解2.1 倉(cāng)庫(kù)地址與鏡像配置不靠譜很多項(xiàng)目默認(rèn)依賴官方公共倉(cāng)庫(kù)但在某些網(wǎng)絡(luò)條件下官方倉(cāng)庫(kù)下載效率確實(shí)不理想。于是大家會(huì)配置鏡像倉(cāng)庫(kù)。鏡像配置本身不復(fù)雜但容易出問(wèn)題的地方在于只配置了 release 倉(cāng)庫(kù)snapshot 倉(cāng)庫(kù)還是走官方或者倉(cāng)庫(kù)順序?qū)懙貌粚?duì)每次構(gòu)建都先嘗試慢的那個(gè)等超時(shí)之后才降級(jí)到快的那個(gè)白白浪費(fèi)時(shí)間還有的鏡像倉(cāng)庫(kù)同步不及時(shí)明明依賴已經(jīng)發(fā)布到官方倉(cāng)庫(kù)鏡像上卻找不到于是報(bào) 404。我見(jiàn)過(guò)最典型的場(chǎng)景是項(xiàng)目里有多個(gè) repository第一個(gè)倉(cāng)庫(kù)填了一個(gè)已經(jīng)失效的內(nèi)網(wǎng)地址第二個(gè)才是能用的公共鏡像。構(gòu)建時(shí)第一個(gè)倉(cāng)庫(kù)連接超時(shí)等半天之后才去第二個(gè)導(dǎo)致每次全量構(gòu)建都很慢還頻繁報(bào)下載失敗。這種問(wèn)題用-X日志能看到請(qǐng)求順序調(diào)整倉(cāng)庫(kù)順序或者直接用鏡像把所有倉(cāng)庫(kù)都“接管”過(guò)來(lái)基本能解決。以 Maven 為例settings.xml里可以使用 mirror 把中央倉(cāng)庫(kù)指向鏡像示例配置如下注意這里的地址是示例實(shí)際換成你們環(huán)境里可用的倉(cāng)庫(kù)地址settings mirrors mirror idexample-mirror/id nameExample Mirror/name urlhttps://mirror.example.com/repository/maven-public//url mirrorOfcentral/mirrorOf /mirror /mirrors /settingsmirrorOf是核心它指定這個(gè)鏡像要替代哪個(gè)倉(cāng)庫(kù)。寫(xiě)central表示只替代中央倉(cāng)庫(kù)寫(xiě)*表示匹配所有倉(cāng)庫(kù)但有內(nèi)網(wǎng)私有倉(cāng)庫(kù)時(shí)千萬(wàn)別用*否則會(huì)把私有倉(cāng)庫(kù)也吞掉。這種配置錯(cuò)誤很隱蔽經(jīng)常導(dǎo)致私有依賴突然下載不到。2.2 緩存把壞包“腌入味”了依賴管理器都會(huì)在本地留緩存本意是加速但一旦之前下載失敗可能會(huì)留下?lián)p壞的臨時(shí)文件。最典型的是 Maven 倉(cāng)庫(kù)里出現(xiàn).lastUpdated后綴的文件還有_remote.repositories記錄里保存了失敗狀態(tài)npm 的 cache 里可能留下不完整的 tarballpip 的 http cache 也可能緩存了損壞的 wheel。當(dāng)你再次構(gòu)建時(shí)工具一看本地有緩存就不再重新下載或者只拿到一個(gè)無(wú)效的元數(shù)據(jù)文件于是反復(fù)失敗。有一個(gè)經(jīng)典現(xiàn)象同事那里下載正常你這邊同一份代碼就是不行。很多時(shí)候不是網(wǎng)絡(luò)差異而是你本地緩存里已經(jīng)存了失敗狀態(tài)。Maven 里可以強(qiáng)制更新快照mvn clean install -U-U會(huì)強(qiáng)制讓 SNAPSHOT 依賴和元數(shù)據(jù)重新檢查更新但注意它不會(huì)自動(dòng)刪除損壞的 jar 或.lastUpdated文件。如果-U沒(méi)用就需要找到對(duì)應(yīng)依賴的緩存目錄手動(dòng)刪掉。Maven 默認(rèn)在~/.m2/repository下按坐標(biāo)路徑存放比如com.example:demo-lib:1.0.0就在~/.m2/repository/com/example/demo-lib/1.0.0/。刪掉該目錄后再重新構(gòu)建一般就能拉回來(lái)。Gradle 的緩存更復(fù)雜分成~/.gradle/caches/modules-2/files-2.1/...和~/.gradle/caches/transforms-*。直接刪整個(gè)~/.gradle/caches很粗暴會(huì)連項(xiàng)目編譯用的其他緩存一起清掉下次構(gòu)建會(huì)慢很多。我通常只刪報(bào)錯(cuò)組件對(duì)應(yīng)目錄或者執(zhí)行./gradlew clean后再在 Gradle 里加--refresh-dependencies./gradlew build --refresh-dependencies這個(gè)命令會(huì)重新解析依賴但不一定會(huì)清理元數(shù)據(jù)緩存必要時(shí)還是手動(dòng)刪。清理緩存的具體原則我會(huì)在第三章里詳細(xì)展開(kāi)。2.3 傳遞依賴把版本樹(shù)攪成一鍋粥“配置其他的依賴庫(kù)”最常踩的坑就是你自己加的依賴沒(méi)問(wèn)題但它又引入了其它傳遞依賴而這些傳遞依賴在倉(cāng)庫(kù)里根本不存在或者版本和項(xiàng)目里現(xiàn)有依賴沖突。比如項(xiàng)目里已經(jīng)用了demo-common:1.2新引入的庫(kù)依賴demo-common:2.0構(gòu)建工具就會(huì)嘗試下載兩個(gè)版本如果倉(cāng)庫(kù)里沒(méi)有其中某一個(gè)就會(huì)報(bào)下載失敗。表面看是“下載失敗”實(shí)際上是版本解析失敗。這種問(wèn)題不能靠連續(xù)點(diǎn)重試解決。第一步是看依賴樹(shù)。Maven 用mvn dependency:tree -DverboseGradle 用./gradlew dependencies --configuration compileClasspath然后觀察報(bào)錯(cuò)的那個(gè)庫(kù)在樹(shù)里的路徑。如果發(fā)現(xiàn)兩個(gè)版本沖突優(yōu)先在構(gòu)建腳本里統(tǒng)一版本而不是暴力排除。例如 Gradle 里可以加全局策略configurations.all { resolutionStrategy { force com.example:demo-common:2.0 } }Maven 則可以用dependencyManagement鎖定版本。強(qiáng)制版本不是萬(wàn)能藥它只能解決“版本統(tǒng)一”如果依賴庫(kù)本身需要某個(gè)不存在的倉(cāng)庫(kù)還是得回到倉(cāng)庫(kù)配置上。這個(gè)先后順序要拎清。2.4 認(rèn)證、證書(shū)和安全策略惹的禍下載私有倉(cāng)庫(kù)里的依賴時(shí)最常見(jiàn)的失敗原因之一是沒(méi)有正確配置倉(cāng)庫(kù)認(rèn)證。倉(cāng)庫(kù)返回 401 或 403但日志不會(huì)直接告訴你“密碼不對(duì)”它可能包裝成Could not transfer artifact。有的項(xiàng)目把用戶名密碼寫(xiě)在pom.xml里這樣做雖然能跑但很容易泄露而且改密碼后要重新提交代碼更穩(wěn)妥的是配置在 Maven 的settings.xml的servers節(jié)點(diǎn)中。證書(shū)問(wèn)題也很隱蔽。有些內(nèi)部倉(cāng)庫(kù)用的證書(shū)不是正規(guī) CA 簽發(fā)的Java 這邊默認(rèn)校驗(yàn)證書(shū)就會(huì)報(bào)SunCertPathBuilderException或PKIX path building failed。不少人第一反應(yīng)是關(guān)掉 SSL 校驗(yàn)這種做法我強(qiáng)烈不建議等于把安全壁壘拆了。正確做法是把內(nèi)部倉(cāng)庫(kù)的根證書(shū)導(dǎo)入 JDK 的cacerts證書(shū)庫(kù)。npm 那邊類似strict-sslfalse也能繞過(guò)檢查但同樣不該在生產(chǎn)項(xiàng)目里長(zhǎng)期使用。如果必須臨時(shí)用記得在本地.npmrc里改不要提交到公共代碼庫(kù)。這里多說(shuō)一句遇到證書(shū)問(wèn)題先別懷疑代碼先把倉(cāng)庫(kù)地址在瀏覽器里打開(kāi)看看如果瀏覽器都提示不安全那基本就是證書(shū)鏈路的問(wèn)題。瀏覽器都能訪問(wèn)且證書(shū)正常再回到依賴管理器配置里找原因。3. 一套可以直接照抄的排查與修復(fù)流程3.1 先給依賴管理器一個(gè)明確的“出路”排查到最后大多數(shù)問(wèn)題都出在“依賴管理器不知道去哪里下載”。所以修復(fù)的第一步不是清緩存也不是改版本而是把倉(cāng)庫(kù)地址梳理清楚。我建議先確認(rèn)下面幾件事項(xiàng)目里用到的所有倉(cāng)庫(kù)地址現(xiàn)在是否還能訪問(wèn)有沒(méi)有統(tǒng)一的公共鏡像地址可以替換默認(rèn)官方倉(cāng)庫(kù)快照和正式版本的倉(cāng)庫(kù)是否分別配置正確私有倉(cāng)庫(kù)的認(rèn)證信息是否已經(jīng)配置在用戶級(jí)配置里。這里有個(gè)原則倉(cāng)庫(kù)地址寧可少而穩(wěn)不要多而雜。我有次為了“加速”在項(xiàng)目里堆了好幾個(gè)鏡像地址結(jié)果構(gòu)建時(shí)每個(gè)倉(cāng)庫(kù)都試一遍最后還因?yàn)榘姹静灰恢聦?dǎo)致下載失敗。后來(lái)只保留一個(gè)鏡像加一個(gè)私有倉(cāng)庫(kù)反而又快又穩(wěn)。對(duì)于大多數(shù)團(tuán)隊(duì)項(xiàng)目有一個(gè)同步及時(shí)的公共鏡像加一個(gè)內(nèi)網(wǎng)私有倉(cāng)庫(kù)存放公司內(nèi)部庫(kù)就足夠了。配置順序也要注意公共鏡像放在前面私有倉(cāng)庫(kù)放在后面或者用 mirror 統(tǒng)一接管。不要把一個(gè)容易超時(shí)的倉(cāng)庫(kù)排在第一位。這部分沒(méi)有標(biāo)準(zhǔn)答案但原則是讓最快最可靠的倉(cāng)庫(kù)先被訪問(wèn)。3.2 Maven 和 Gradle 項(xiàng)目的倉(cāng)庫(kù)切換示例Maven 項(xiàng)目切換鏡像除了前面說(shuō)的settings.xml里配置 mirror還可以在項(xiàng)目pom.xml里聲明 repository但需要注意pom.xml里的 repository 優(yōu)先級(jí)和 settings 里的 mirror 是不同的。mirror 相當(dāng)于攔截器會(huì)影響所有倉(cāng)庫(kù)訪問(wèn)project 里聲明 repository 是直接指定。我一般建議團(tuán)隊(duì)統(tǒng)一在用戶級(jí)settings.xml里配 mirror這樣即使項(xiàng)目里寫(xiě)死了舊地址也能被鏡像接管。關(guān)于私有倉(cāng)庫(kù)的認(rèn)證可以在settings.xml里配置serverssettings servers server idprivate-repo/id usernamedeploy-user/username passwordencrypted-password/password /server /servers /settingsGradle 項(xiàng)目則是在build.gradle里配置repositories { maven { url https://mirror.example.com/repository/maven-public/ } maven { url https://repo.example.com/private-releases/ credentials { username deploy-user password encrypted-password } } }注意mavenLocal()要慎重它會(huì)優(yōu)先使用本機(jī)~/.m2/repository里已有的包。如果本機(jī)緩存里正好有一個(gè)不對(duì)的版本即使遠(yuǎn)程倉(cāng)庫(kù)有正確版本它也會(huì)優(yōu)先用本地的從而出現(xiàn)“本地能用、CI 不能跑”的幽靈問(wèn)題。團(tuán)隊(duì)協(xié)作時(shí)我習(xí)慣把它注釋掉。改完倉(cāng)庫(kù)配置后建議執(zhí)行一次mvn clean install -U或./gradlew clean build --refresh-dependencies確認(rèn)下載是否恢復(fù)。3.3 npm 和 pip 的快速修復(fù)套路前端項(xiàng)目里 npm 下載失敗通常先從.npmrc入手。項(xiàng)目根目錄.npmrc可以臨時(shí)覆蓋用戶級(jí)配置但注意里面寫(xiě)的倉(cāng)庫(kù)地址會(huì)隨代碼提交如果里面包含內(nèi)部倉(cāng)庫(kù)地址別公開(kāi)倉(cāng)庫(kù)。一個(gè)常見(jiàn)的.npmrc示例registryhttps://registry.example.com/ fetch-retries3 fetch-retry-factor2 fetch-retry-mintimeout10000 fetch-retry-maxtimeout60000如果之前下載失敗留下了壞緩存可以執(zhí)行npm cache clean --force rm -rf node_modules npm install這里我要特別說(shuō)明package-lock.json不要隨便刪除非你已經(jīng)確定是鎖文件里的某個(gè) resolved 地址失效了。直接刪掉鎖文件會(huì)導(dǎo)致所有依賴版本重新解析項(xiàng)目里其他同事用的版本可能和你不一樣容易埋雷。更安全的做法是刪掉node_modules和 npm 緩存保留鎖文件重新安裝如果鎖文件里的 resolved 地址確實(shí)訪問(wèn)不了再編輯鎖文件或重新生成。Python 項(xiàng)目用 pip 時(shí)最常見(jiàn)的下載失敗是超時(shí)和Could not find a version that satisfies the requirement。可以先把索引切到公共鏡像然后在命令里加pip install --no-cache-dir -r requirements.txt -i https://pypi.example.com/simple--no-cache-dir能跳過(guò)本地緩存適合排查“緩存了壞包”的情況。但每次都加參數(shù)太啰嗦可以用配置文件pip config set global.index-url https://pypi.example.com/simple如果某個(gè)包帶了二進(jìn)制擴(kuò)展在鏡像上沒(méi)有對(duì)應(yīng)操作系統(tǒng)的 wheel也會(huì)下載失敗。那就要檢查鏡像是否覆蓋了當(dāng)前平臺(tái)的 wheel或者臨時(shí)從項(xiàng)目官方頁(yè)面下載對(duì)應(yīng)文件。遇到這種問(wèn)題報(bào)錯(cuò)信息里通常會(huì)提到Looking in links或No matching distribution需要多看兩行別死盯最后一行。3.4 清理緩存時(shí)要守住“最小范圍”原則新手遇到下載失敗喜歡直接刪整個(gè)緩存目錄比如把整個(gè)~/.m2/repository或node_modules刪掉這雖然經(jīng)常能解決問(wèn)題但代價(jià)很大。全量重建會(huì)觸發(fā)大量依賴重新下載萬(wàn)一網(wǎng)絡(luò)本來(lái)就不穩(wěn)定反而陷入“越刪越失敗”的循環(huán)。正確做法是針對(duì)報(bào)錯(cuò)的那一個(gè)依賴精準(zhǔn)清理。先定位錯(cuò)誤里提到的組件名再到本地緩存目錄找到對(duì)應(yīng)子目錄刪除。對(duì)于 Maven刪除坐標(biāo)目錄后下一構(gòu)建會(huì)自動(dòng)重新下載對(duì)于 Gradle刪除modules-2下對(duì)應(yīng)組件目錄對(duì)于 npm可以先npm cache clean --force再刪node_modules里的對(duì)應(yīng)包pip 刪除對(duì)應(yīng)包后再用pip install --no-cache-dir。還有一個(gè)容易忽略的點(diǎn)磁盤(pán)滿了。萬(wàn)一用戶目錄所在分區(qū)可用空間不夠下載一半會(huì)報(bào)No space left on device。這種報(bào)錯(cuò)看日志會(huì)給人一種“依賴壞了”的錯(cuò)覺(jué)其實(shí)是寫(xiě)不進(jìn)去。檢查一下各分區(qū)空間把大緩存目錄清一輪問(wèn)題立解。所以“清理緩存”不光是清理壞包也是給下載騰空間。4. 常見(jiàn)問(wèn)題速查與避坑經(jīng)驗(yàn)4.1 下載失敗問(wèn)題速查表我把實(shí)際以及身邊同事遇到過(guò)的依賴下載失敗問(wèn)題整理成了速查表方便以后直接對(duì)照。現(xiàn)象可能原因優(yōu)先排查方向連接超時(shí)倉(cāng)庫(kù)網(wǎng)絡(luò)慢、倉(cāng)庫(kù)地址不通、超時(shí)設(shè)置太短換鏡像、增加超時(shí)、確認(rèn)地址可訪問(wèn)403/401私有倉(cāng)庫(kù)認(rèn)證失敗、賬號(hào)過(guò)期更新認(rèn)證信息不要寫(xiě)在項(xiàng)目里404依賴不存在、鏡像未同步、版本號(hào)拼寫(xiě)錯(cuò)誤檢查版本是否存在、切到官方倉(cāng)庫(kù)確認(rèn)Checksum mismatch下載文件損壞、鏡像同步出錯(cuò)刪除緩存重下、換另一個(gè)鏡像PKIX path building failed證書(shū)鏈不被信任導(dǎo)入根證書(shū)不建議關(guān)掉校驗(yàn)No space left on device磁盤(pán)滿了清理緩存目錄、擴(kuò)大分區(qū)Could not resolve dependencies傳遞依賴缺失或版本沖突看依賴樹(shù)統(tǒng)一版本或補(bǔ)倉(cāng)庫(kù)這張表覆蓋了八成以上的“總是下載失敗”場(chǎng)景。剩下兩成往往需要把-X日志發(fā)給包維護(hù)者或倉(cāng)庫(kù)管理員讓熟悉環(huán)境的人看一眼請(qǐng)求鏈路才能定位。4.2 我從實(shí)際項(xiàng)目里總結(jié)的六條避坑清單第一不要為了“快”把超時(shí)時(shí)間調(diào)到無(wú)窮大。你等一個(gè)壞依賴一小時(shí)不如花十分鐘把根因查出來(lái)。超時(shí)是安全繩不是用來(lái)背鍋的。第二修改倉(cāng)庫(kù)配置后一定要強(qiáng)制刷新。Maven 里光改settings.xml還不夠要執(zhí)行mvn -U。為什么因?yàn)楸镜鼐彺娴脑獢?shù)據(jù)可能已經(jīng)記錄了“這個(gè)版本不存在”或“這個(gè)倉(cāng)庫(kù)不可用”不強(qiáng)制刷新構(gòu)建還是會(huì)走舊路徑。第三不要把私有倉(cāng)庫(kù)的密碼提交到代碼倉(cāng)庫(kù)。即使項(xiàng)目能在你機(jī)器上跑別人克隆下來(lái)也大概率會(huì)報(bào)認(rèn)證失敗。配置settings.xml或環(huán)境變量既能保證不同環(huán)境差異又不會(huì)泄露秘密。第四不要看到版本沖突就無(wú)腦排除。先看依賴樹(shù)確認(rèn)沖突的根節(jié)點(diǎn)是誰(shuí)。有些沖突只需要把兩個(gè)依賴的版本統(tǒng)一并不需要排除傳遞依賴如果排除錯(cuò)了反而會(huì)丟類報(bào)NoClassDefFoundError。第五同一個(gè)依賴不要在多個(gè)倉(cāng)庫(kù)里各放一份“差不多”的版本。很多下載失敗其實(shí)是倉(cāng)庫(kù)之間的內(nèi)容不一致造成的你在這個(gè)倉(cāng)庫(kù)能找到 1.0.1那個(gè)倉(cāng)庫(kù)只有 1.0.0構(gòu)建時(shí)拿到哪個(gè)完全取決于排序。公司內(nèi)部盡量統(tǒng)一一個(gè)私有倉(cāng)庫(kù)作為權(quán)威源。第六鎖文件是團(tuán)隊(duì)協(xié)作的“契約”。npm 的package-lock.json、pip 的requirements.txt鎖版本、Maven 的dependencyManagement這些機(jī)制就是為了防止依賴漂移。遇到下載失敗別急著刪鎖文件先確認(rèn)鎖文件里的地址是不是還活著。5. 把“下載失敗”擋在項(xiàng)目啟動(dòng)前5.1 項(xiàng)目啟動(dòng)時(shí)先做一次依賴健康檢查我在處理這類問(wèn)題的過(guò)程中慢慢養(yǎng)成一個(gè)習(xí)慣每次新項(xiàng)目開(kāi)始先把倉(cāng)庫(kù)源和依賴清單固定下來(lái)而不是等到下載失敗才回頭折騰。具體說(shuō)就是項(xiàng)目啟動(dòng)時(shí)花五分鐘檢查默認(rèn)鏡像是否可用私有倉(cāng)庫(kù)地址和認(rèn)證是否寫(xiě)到用戶級(jí)配置里依賴版本不要用不帶版本號(hào)的latest或盡量用鎖文件或父工程管理版本。這樣后面省下的時(shí)間遠(yuǎn)遠(yuǎn)超過(guò)這五分鐘。這個(gè)檢查不需要太復(fù)雜新建一個(gè)空項(xiàng)目加入一個(gè)你最常用的依賴執(zhí)行一次安裝命令。如果這一步順利說(shuō)明基礎(chǔ)倉(cāng)庫(kù)鏈路沒(méi)問(wèn)題。之后每加一個(gè)重量級(jí)新依賴都要留意它是否帶了一堆額外的傳遞依賴避免把版本樹(shù)攪亂。5.2 CI 里把依賴緩存當(dāng)一等公民對(duì)待很多人只在本地開(kāi)發(fā)時(shí)關(guān)心依賴下載卻忽略了 CI 環(huán)境。CI 每次從零裝依賴非常耗時(shí)也更容易觸發(fā)下載失敗因?yàn)?CI 的網(wǎng)絡(luò)和本機(jī)往往不一樣。我習(xí)慣把依賴緩存目錄加入 CI 的緩存策略比如 Maven 緩存~/.m2/repositoryGradle 緩存~/.gradle/cachesnpm 緩存~/.npmpip 緩存~/.cache/pip。這樣下次構(gòu)建能復(fù)用大部分依賴只有真正變化的包才會(huì)重新下載。不過(guò)緩存也要設(shè)上限否則 CI 緩存目錄會(huì)越滾越大最終因?yàn)槿萘繂?wèn)題被清理掉等于白配。另外緩存策略要綁定倉(cāng)庫(kù)源如果換了鏡像舊緩存里的“失敗記錄”可能會(huì)繼續(xù)影響新構(gòu)建所以 CI 里倉(cāng)庫(kù)配置要和本地保持一致。還有一個(gè)小技巧Maven 項(xiàng)目可以在 CI 里先跑一次mvn dependency:go-offline把依賴提前拉到本地緩存后續(xù)構(gòu)建速度會(huì)明顯提升。5.3 一點(diǎn)關(guān)于排查節(jié)奏的個(gè)人體會(huì)最后說(shuō)說(shuō)心態(tài)。依賴下載失敗這種問(wèn)題最怕連續(xù)無(wú)腦點(diǎn)重試。我給自己定過(guò)一個(gè)規(guī)矩同一個(gè)問(wèn)題連續(xù)重試不超過(guò)三次。第一次看完整日志確認(rèn)錯(cuò)誤層級(jí)第二次看本地緩存確認(rèn)是不是壞包或失敗記錄第三次查倉(cāng)庫(kù)配置和版本策略。如果三次還沒(méi)定位到就把日志存好離開(kāi)工位休息一下。因?yàn)橐蕾噯?wèn)題往往牽涉到網(wǎng)絡(luò)、證書(shū)、私有倉(cāng)庫(kù)同步等“看不見(jiàn)”的因素硬剛效率很低。但只要你把日志留好休息一會(huì)兒再回頭通常會(huì)發(fā)現(xiàn)之前漏掉的某個(gè)關(guān)鍵字。依賴下載失敗這件事大多數(shù)時(shí)候都不是“運(yùn)氣不好”而是倉(cāng)庫(kù)配置、緩存狀態(tài)和版本策略三者配合出了問(wèn)題。下次再遇到“項(xiàng)目里配置其他的依賴庫(kù)卻總是下載失敗”時(shí)先別盯著紅色日志發(fā)呆從看日志層級(jí)開(kāi)始一步一步來(lái)。這套流程我已經(jīng)用了很多次基本上每次都能把問(wèn)題控制在半小時(shí)內(nèi)解決。