又一次在 CI 日志里看到ReadTimeoutError下部躺著一行pip install 第三方庫(kù)的失敗記錄。這場(chǎng)景太熟悉了同事試了三次換網(wǎng)絡(luò)、重啟還是超時(shí)。實(shí)際上大多數(shù)這類問(wèn)題用一行帶-i參數(shù)的 pip 安裝命令就能解決成本低到可以忽略效果卻立竿見(jiàn)影。這個(gè)辦法解決的不是某一次運(yùn)氣不好而是要理解 pip 安裝時(shí)的超時(shí)到底從哪來(lái)。只有把鏈路看清楚才談得上一行代碼根治。下面我會(huì)從報(bào)錯(cuò)定位、臨時(shí)換源、持久配置、到換完源還超時(shí)的完整排查鏈路把這些年在各種環(huán)境下踩過(guò)的坑一次說(shuō)清楚。1. 先定位 pip 超時(shí)這個(gè)坑到底卡在哪一個(gè)環(huán)節(jié)1.1 一條 pip install 命令背后要連幾次源估計(jì)很多人在pip install xxx卡住的時(shí)候心里默認(rèn)它就是一次性下載一個(gè)文件。實(shí)際上 pip 的安裝過(guò)程需要跟包索引服務(wù)器進(jìn)行好幾輪交互pip 先把你要裝的包名拼成一個(gè)索引頁(yè)地址例如官方默認(rèn)源里的/simple/包名/然后把整個(gè)包的版本列表抓回來(lái)。解析完 HTML 后pip 會(huì)從列表里挑出符合當(dāng)前 Python 版本、操作系統(tǒng)、硬件平臺(tái)的輪子.whl 文件或源碼包再發(fā)起真正的文件下載。如果這個(gè)包還帶依賴pip 需要把自己解析出來(lái)的每個(gè)依賴項(xiàng)挨個(gè)重復(fù)上面兩輪網(wǎng)絡(luò)請(qǐng)求最終才能組成一個(gè)完整的安裝方案。也就是說(shuō)哪怕你只想裝一個(gè)很小的第三方庫(kù)只要它的依賴樹稍微大一點(diǎn)實(shí)際發(fā)生的網(wǎng)絡(luò)請(qǐng)求可能是幾十次。平時(shí)我們只看到最后那條 time out至于到底是哪一輪斷開(kāi)日志里有時(shí)寫得并不明顯。這也能解釋一個(gè)錯(cuò)覺(jué)有些包明明只有幾十 KB卻依然會(huì)超時(shí)。因?yàn)榭ㄗ〉奈恢酶静辉谧罱K那個(gè)文件下載而是前面的索引頁(yè)或依賴解析環(huán)節(jié)沒(méi)有順利拿到響應(yīng)。1.2 讀懂報(bào)錯(cuò)種類比滿屏找加大超時(shí)時(shí)間更重要不同報(bào)錯(cuò)詞對(duì)應(yīng)的修復(fù)方向差很遠(yuǎn)。我遇到過(guò)最常見(jiàn)的幾種報(bào)錯(cuò)關(guān)鍵詞直觀表現(xiàn)主要成因ConnectTimeoutError連接源服務(wù)器時(shí)就沒(méi)握手成功源服務(wù)器完全不可達(dá)或網(wǎng)絡(luò)路由不通ReadTimeoutError連接建立了但響應(yīng)遲遲不來(lái)鏈路太慢、源站響應(yīng)慢或者文件下載一半卡住ConnectionError連接過(guò)程中被斷開(kāi)或拒絕代理異常、DNS 解析失敗、源站暫時(shí)抖動(dòng)Retry提示同一請(qǐng)求反復(fù)失敗前一次超時(shí)后pip 自動(dòng)重試多次很多人一看ReadTimeoutError就先加--timeout 9999這屬于治標(biāo)不治本。如果源服務(wù)器的鏈路質(zhì)量很差加長(zhǎng)超時(shí)只會(huì)讓你等更久最后依然失敗。默認(rèn)情況下pip 的 timeout 大概是 15 秒對(duì)跨國(guó)下載大型二進(jìn)制輪子來(lái)說(shuō)這個(gè)時(shí)間確實(shí)偏緊但它不是超時(shí)的根本原因。想看得更清楚安裝時(shí)加-v或者-vvvpip 會(huì)把每次請(qǐng)求的 URL、重試狀態(tài)都打出來(lái)。比如python -m pip install 某個(gè)包 -vvv日志里如果出現(xiàn)Looking in indexes: https://pypi.org/simple說(shuō)明它還在用默認(rèn)的官方源那么后續(xù)超時(shí)的風(fēng)險(xiǎn)點(diǎn)基本就能鎖定在跨網(wǎng)訪問(wèn)這條鏈路上。1.3 換命令之前先花 10 秒做一次連通性偵察我現(xiàn)在的習(xí)慣是不急著盲改命令直接用curl快速測(cè)一下源地址的響應(yīng)情況。比如測(cè)一下官方源某個(gè)常見(jiàn)索引頁(yè)curl -sSI -m 5 https://pypi.org/simple/requests/如果這個(gè)命令在 5 秒內(nèi)都能正常返回 HTTP 響應(yīng)頭說(shuō)明網(wǎng)絡(luò)到官方源的基本通路是通的只是速度可能不理想。如果直接卡住超時(shí)那就基本可以確認(rèn)你的網(wǎng)絡(luò)環(huán)境訪問(wèn)官方源這條路本身就很慢。同樣的方法再測(cè)一個(gè)你打算切換的鏡像源比如curl -sSI -m 5 https://某個(gè)鏡像源地址/simple/requests/兩條結(jié)果一對(duì)比好壞立判。這一步雖然多花了十幾秒但能避免你盲目重試、反復(fù)踩相同的超時(shí)是排查網(wǎng)絡(luò)問(wèn)題最直接的抓手。2. 一行代碼的真正寫法臨時(shí)換源加合理超時(shí)2.1 最簡(jiǎn)單有效的 -i 參數(shù)一次性安裝某個(gè)第三方庫(kù)時(shí)用-i臨時(shí)指定一個(gè)新的索引源寫法如下pip install requests -i https://mirrors.example.com/simple實(shí)際使用時(shí)把https://mirrors.example.com/simple替換成你所在網(wǎng)絡(luò)環(huán)境下訪問(wèn)最快的鏡像源地址。注意末尾的/simple不能隨便去掉這是 PyPI 包索引目錄服務(wù)的約定路徑很多鏡像也都遵循這一層結(jié)構(gòu)。這個(gè)命令好在哪里它不會(huì)修改全局配置文件不影響系統(tǒng)里其他 Python 項(xiàng)目。比如你只是為了快速裝一個(gè)包進(jìn)虛擬環(huán)境沒(méi)必要?jiǎng)尤衷O(shè)置又比如你怕破壞了同事機(jī)器上的既有環(huán)境那用這種臨時(shí)參數(shù)最溫和。-i參數(shù)只對(duì)當(dāng)前這一條命令生效用完就結(jié)束。如果遇到的是安裝依賴樹很深的項(xiàng)目比如某個(gè)框架帶了幾十個(gè)傳遞依賴-i指定的索引同樣會(huì)被依賴解析過(guò)程沿用相當(dāng)于整棵依賴樹都從新源拿。這也是為什么一行換源經(jīng)常能把整個(gè)安裝過(guò)程從反復(fù)超時(shí)救回來(lái)。2.2 加上 --timeout 與 --retries兜住大文件下載有些時(shí)候單獨(dú)換源后依然偶發(fā)超時(shí)。比如你下載的是一個(gè)幾百 MB 的機(jī)器學(xué)習(xí)輪子或者公司網(wǎng)絡(luò)本來(lái)就波動(dòng)大那可以在后面補(bǔ)兩個(gè)參數(shù)pip install 某個(gè)第三方庫(kù) -i https://mirrors.example.com/simple --timeout 60 --retries 5--timeout 60表示每次連接和讀取的最長(zhǎng)等待時(shí)間是 60 秒--retries 5表示失敗后最多重試 5 次。它們的價(jià)值不是用來(lái)對(duì)抗慢源而是對(duì)抗網(wǎng)絡(luò)抖動(dòng)給安裝過(guò)程多一點(diǎn)容錯(cuò)。默認(rèn) 15 秒這個(gè)值在加載大模型依賴、本地沒(méi)有緩存、網(wǎng)絡(luò)高峰期確實(shí)有點(diǎn)緊張。這里有個(gè)小經(jīng)驗(yàn)優(yōu)先寫python -m pip install而不是裸寫pip install比如python -m pip install requests -i https://mirrors.example.com/simple原因很簡(jiǎn)單python -m pip能保證你調(diào)用的 pip 是你當(dāng)前 Python 解釋器對(duì)應(yīng)的那個(gè)避免系統(tǒng)里存在多個(gè) Python、多個(gè) pip 時(shí)出現(xiàn)裝了包卻發(fā)現(xiàn) import 不到的詭異現(xiàn)象。尤其是在虛擬環(huán)境和多版本 Python 并存的環(huán)境里這也算一種預(yù)防性習(xí)慣。2.3 到底該用臨時(shí)參數(shù)還是永久配置臨時(shí)參數(shù)適合的場(chǎng)景跑一次性的腳本依賴安裝、臨時(shí)進(jìn)容器調(diào)試、在別人機(jī)器上救火。永久配置適合的場(chǎng)景你自己日常開(kāi)發(fā)機(jī)、團(tuán)隊(duì)統(tǒng)一 CI 基礎(chǔ)鏡像、以及任何需要反復(fù)安裝依賴的工作流。我見(jiàn)過(guò)有人每次安裝都敲一長(zhǎng)串-i參數(shù)敲了半年還重復(fù)敲這就是沒(méi)想清楚該把配置固化下來(lái)。如果你是一個(gè)長(zhǎng)期在這類網(wǎng)絡(luò)環(huán)境里開(kāi)發(fā)的人與其記住一串命令不如進(jìn)入第 3 節(jié)的持久化配置一勞永逸。3. 真正減少踩坑的改法全局源配置一次性寫好3.1 用 pip config 命令一鍵寫進(jìn)配置文件pip 從某個(gè)版本開(kāi)始提供了pip config子命令不用手動(dòng)找配置文件路徑也不用記憶 INI 格式直接執(zhí)行pip config set global.index-url https://mirrors.example.com/simple pip config set global.timeout 60 pip config set global.trusted-host mirrors.example.com第一條設(shè)置的是默認(rèn)索引地址第二條把超時(shí)從 15 秒調(diào)長(zhǎng)到 60 秒第三條用來(lái)聲明這個(gè)鏡像主機(jī)是可信來(lái)源。執(zhí)行完可以用pip config list查看當(dāng)前生效的所有配置。這里有一點(diǎn)要注意如果鏡像地址是 HTTPS 的絕大多數(shù)情況不需要設(shè)置trusted-host如果你所在環(huán)境提供的是 HTTP 地址pip 出于安全考慮會(huì)拒絕使用才需要配合trusted-host聲明。能用 HTTPS 盡量用 HTTPS安全性和穩(wěn)定性都更好。pip config set默認(rèn)寫在當(dāng)前用戶的配置里而不是系統(tǒng)級(jí)位置。對(duì)個(gè)人開(kāi)發(fā)環(huán)境來(lái)說(shuō)這是最合理的作用域既不會(huì)影響系統(tǒng)內(nèi)置 Python也不需要管理員權(quán)限。3.2 手工修改配置文件時(shí)不同平臺(tái)的位置別搞錯(cuò)有人更喜歡直接編輯配置文件那我順手把常見(jiàn)平臺(tái)的位置列一下平臺(tái)用戶級(jí)配置文件路徑Linux / macOS~/.pip/pip.conf或~/.config/pip/pip.confWindows%APPDATA%\pip\pip.ini配置文件內(nèi)容用 INI 格式例如[global] index-url https://mirrors.example.com/simple timeout 60 trusted-host mirrors.example.com注意index-url的值不要帶末尾的斜杠寫成類似https://mirrors.example.com/simple就好。改完配置文件可以用pip config list驗(yàn)證一下新值有沒(méi)有被讀取。如果哪天想徹底取消全局換源或者改回官方源直接執(zhí)行pip config unset global.index-url或者手動(dòng)刪掉配置文件里對(duì)應(yīng)那行比去網(wǎng)上搜索怎么恢復(fù)默認(rèn)源快得多。3.3 多鏡像冗余安裝時(shí)自動(dòng)補(bǔ)位有沒(méi)有可能一個(gè)源掛了另一個(gè)源頂上有但需要你把命令寫得稍微細(xì)一點(diǎn)。可以利用extra-index-url配置項(xiàng)它表示除主索引外再去額外索引里找包。在pip.conf里寫成[global] index-url https://mirrors-a.example.com/simple extra-index-url https://mirrors-b.example.com/simple這樣安裝時(shí)pip 先查主源如果主源里沒(méi)有這個(gè)包會(huì)去備用源找。不過(guò)要注意extra-index-url是并行候選索引并不是嚴(yán)格意義上的失敗自動(dòng)切換。如果主源連不上pip 仍可能報(bào)錯(cuò)不一定每次都能自動(dòng)落到備用源上。真正想實(shí)現(xiàn)第一個(gè)源失敗自動(dòng)換第二個(gè)源的穩(wěn)妥做法是寫一個(gè)很小的安裝函數(shù)pip_install_spare() { pip install $ -i https://mirrors-a.example.com/simple || \ pip install $ -i https://mirrors-b.example.com/simple }執(zhí)行pip_install_spare 某個(gè)包主源失敗時(shí)下一條命令自動(dòng)用備用源補(bǔ)救。這屬于笨辦法但在實(shí)戰(zhàn)里特別管用尤其是你要批量給多臺(tái)機(jī)器裝環(huán)境時(shí)能省掉半夜盯日志的麻煩。4. 換完源依舊超時(shí)逐個(gè)排查下來(lái)真正有效的定位鏈路4.1 先確認(rèn)不是鏡像地址寫法本身有坑換了源還在超時(shí)第一件事不是懷疑命令而是看鏡像地址對(duì)不對(duì)。常見(jiàn)的坑有三個(gè)地址寫錯(cuò)成https://mirrors.example.com缺了/simple導(dǎo)致 pip 直接請(qǐng)求一個(gè)不存在的目錄。鏡像源是 HTTP而你沒(méi)有設(shè)置trusted-hostpip 在安全檢查階段就拒絕了連接。鏡像源本身不支持你本地 Python 版本對(duì)應(yīng)的文件格式導(dǎo)致 pip 反復(fù)嘗試請(qǐng)求不存在的文件。這種情況少見(jiàn)但偶爾會(huì)出現(xiàn)。驗(yàn)證方法還是用 curl直接請(qǐng)求索引頁(yè)curl -sSI -m 10 https://mirrors.example.com/simple/某個(gè)包/能返回200 OK或200系列狀態(tài)碼說(shuō)明鏡像基本可用。如果返回 403、404那就要重新檢查地址了。4.2 大文件下載中斷清理緩存和本地安裝才是解藥很多大型第三方庫(kù)的輪子動(dòng)輒幾百 MB網(wǎng)絡(luò)稍微抖一下下載到一半就可能斷掉。這時(shí)候加超時(shí)參數(shù)作用有限因?yàn)閱?wèn)題不再是響應(yīng)慢而是連接不穩(wěn)定導(dǎo)致傳輸中斷。第一招是清理本地緩存把可能損壞的緩存文件清掉pip cache purge如果緩存本身壞了即使你換了源pip 也可能反復(fù)拿損壞的緩存文件去校驗(yàn)然后失敗。強(qiáng)制不走緩存再試一次pip install 某個(gè)包 -i https://mirrors.example.com/simple --no-cache-dir第二招更穩(wěn)在鏡像站點(diǎn)上下載對(duì)應(yīng)的.whl文件到本地然后用本地文件安裝wget -c https://mirrors.example.com/simple/某個(gè)包/某個(gè)包-1.0.0-py3-none-any.whl pip install ./某個(gè)包-1.0.0-py3-none-any.whlwget -c的斷點(diǎn)續(xù)傳能力比 pip 自帶的下載邏輯對(duì)網(wǎng)絡(luò)波動(dòng)更寬容下載中斷后重新執(zhí)行會(huì)從斷點(diǎn)繼續(xù)而不是從頭再來(lái)。等文件完整落到本地pip 安裝時(shí)就幾乎不依賴網(wǎng)絡(luò)了。這個(gè)方法特別適合那些構(gòu)造復(fù)雜的底層依賴包。4.3 代理環(huán)境變量會(huì)讓一行代碼完全失效這是換完源依舊超時(shí)時(shí)最容易被人忽略的隱藏因素。當(dāng)你運(yùn)行 pip 時(shí)它會(huì)主動(dòng)讀取系統(tǒng)環(huán)境變量里的代理配置比如http_proxy、https_proxy、all_proxy。如果這些變量指向一個(gè)不穩(wěn)定或已經(jīng)失效的代理服務(wù)那么不管你換成哪個(gè)鏡像源所有請(qǐng)求都會(huì)先被強(qiáng)行導(dǎo)向代理去繞一圈。代理一旦不給力time out 就照舊。排查命令env | grep -i proxy如果輸出里能看到相關(guān)的代理變量說(shuō)明當(dāng)前 shell 環(huán)境被設(shè)置了代理。你可以在當(dāng)前終端里臨時(shí)清掉再執(zhí)行安裝unset http_proxy https_proxy all_proxy python -m pip install 某個(gè)包 -i https://mirrors.example.com/simple這種情況在我身邊出現(xiàn)過(guò)不止一次公司統(tǒng)一給辦公網(wǎng)配置了代理開(kāi)發(fā)機(jī)上也繼承了代理變量結(jié)果 pip 換源后依然超時(shí)。清掉代理后直連鏡像源反而非常順暢。需要說(shuō)明的是某些公司內(nèi)網(wǎng)環(huán)境離開(kāi)代理確實(shí)無(wú)法訪問(wèn)外網(wǎng)那就另當(dāng)別論這里只針對(duì)代理本身不可用卻還在環(huán)境變量里躺著的情況。4.4 你看到的超時(shí)可能是 pip 正在本地編譯源碼包最后這個(gè)坑比較隱蔽日志下方已經(jīng)出現(xiàn) time out 字樣但實(shí)際上 pip 并沒(méi)有在網(wǎng)絡(luò)請(qǐng)求上卡住而是在為某個(gè)依賴構(gòu)建輪子。當(dāng)索引里找不到合適的預(yù)編譯輪子時(shí)pip 會(huì)下載源碼包.tar.gz然后在本地用編譯器構(gòu)建。如果依賴項(xiàng)很多構(gòu)建過(guò)程可能持續(xù)幾分鐘期間日志更新時(shí)間很慢看起來(lái)像卡死了。加上有些 CI 系統(tǒng)對(duì)命令輸出有超時(shí)上限于是你看到的是整體超時(shí)而不是網(wǎng)絡(luò)層面的 timeout。判斷方法很簡(jiǎn)單安裝時(shí)用-v查看輸出如果出現(xiàn)Building wheel for xxx或者Running setup.py bdist_wheel這類內(nèi)容說(shuō)明 pip 在編譯而不是在下載。這種情況下你不是網(wǎng)絡(luò)慢而是缺了本地構(gòu)建環(huán)境。可以去對(duì)應(yīng)庫(kù)的文檔里找對(duì)應(yīng)的預(yù)編譯 wheel 名稱或者先安裝好本地編譯器工具鏈再重試安裝。5. 我為長(zhǎng)期不被超時(shí)折磨攢下的幾條經(jīng)驗(yàn)5.1 選源時(shí)別只看快還要看穩(wěn)和全快和穩(wěn)不是一回事。我曾經(jīng)試過(guò)某個(gè)源雖然延遲很低但同步不及時(shí)新發(fā)的包版本要隔很久才出現(xiàn)結(jié)果安裝特定新版本時(shí)報(bào)404 Not Found。所以選源我一般按這個(gè)順序判斷優(yōu)先使用 HTTPS 的鏡像源避免明文協(xié)議帶來(lái)的下載內(nèi)容被干擾。優(yōu)先選擇更新頻率高的鏡像盡量保證新包能及時(shí)出現(xiàn)。遇到超大文件下載先用 curl 測(cè)試實(shí)際傳輸速度而不是只測(cè)首頁(yè)能不能打開(kāi)。不要迷信單一源是萬(wàn)能藥關(guān)鍵時(shí)刻要能快速切到備用源。5.2 在虛擬環(huán)境和 Docker 構(gòu)建里提前固化配置如果只是在本地開(kāi)發(fā)手工執(zhí)行配置就夠了。但如果你是給團(tuán)隊(duì)維護(hù)一套基礎(chǔ)環(huán)境我會(huì)建議把源配置寫進(jìn) Dockerfile 或者虛擬環(huán)境創(chuàng)建腳本里而不是靠每個(gè)人手動(dòng)敲命令。Docker 構(gòu)建時(shí)常用的做法是先設(shè)置環(huán)境變量再做安裝ENV PIP_INDEX_URLhttps://mirrors.example.com/simple ENV PIP_TIMEOUT60 RUN pip install --no-cache-dir -r requirements.txt這樣做的好處是鏡像構(gòu)建過(guò)程中每一次pip install默認(rèn)都會(huì)走鏡像源不需要額外加-i參數(shù)。以后別人用你這份 Dockerfile 構(gòu)建時(shí)也不會(huì)因?yàn)閭€(gè)人環(huán)境不同而觸發(fā)超時(shí)。5.3 安裝前 10 秒想兩個(gè)問(wèn)題能少踩很多超時(shí)我現(xiàn)在安裝第三方庫(kù)前已經(jīng)習(xí)慣快速問(wèn)自己兩個(gè)問(wèn)題這個(gè)包的體量是不是很大我當(dāng)前所在網(wǎng)絡(luò)訪問(wèn)默認(rèn)源是否穩(wěn)定如果答案都是是我會(huì)直接跳過(guò)裸裝命令用帶鏡像源和較長(zhǎng)超時(shí)參數(shù)的安裝命令。如果答案涉及本地編譯我還會(huì)先確認(rèn)目標(biāo)機(jī)器有沒(méi)有對(duì)應(yīng)編譯器。別小看這 10 秒它把你從反復(fù)失敗再反復(fù)嘗試的循環(huán)里拉出來(lái)安裝體驗(yàn)會(huì)好非常多。