高效解決 pip install 報錯 SSLError: EOF occurred in violation of protocol

標簽： Python, pip, SSLError, Clash, 網絡代理, 問題解決

一、問題描述

在Python開發中，pip 是我們最親密的伙伴。然而，當你身處需要科學上網的環境，并在終端（尤其是開啟了Clash for Windows等網絡代理工具時）中滿懷期待地敲下 pip install some-package 時，卻可能遭遇一個令人困惑的紅色錯誤：

WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by ‘SSLError(SSLError(8, ‘EOF occurred in violation of protocol (_ssl.c:1125)’))’: /simple/pycocotools/
…
Could not fetch URL https://pypi.org/simple/pycocotools/: There was a problem confirming the ssl certificate: HTTPSConnectionPool(host=‘pypi.org’, port=443): Max retries exceeded with url: /simple/pycocotools/ (Caused by SSLError(SSLError(8, ‘EOF occurred in violation of protocol (_ssl.c:1125)’))) - skipping
ERROR: Could not find a version that satisfies the requirement pycocotools
ERROR: No matching distribution found for pycocotools
在 VS Code 的終端中，嘗試安裝 pycocotools 時就出現了這個典型的 SSLError 錯誤。

這個錯誤的核心信息是 SSLError: EOF occurred in violation of protocol，直譯過來就是“在違反協議的情況下發生了EOF（文件結束符）”，這通常意味著SSL/TLS握手過程意外中斷。

二、錯誤原因分析

從錯誤信息中的 SSLError 和 HTTPSConnectionPool 關鍵字可以看出，這顯然是一個網絡層面的問題，而不是你嘗試安裝的 Python 包（例如 pycocotools）本身有問題。

它指的是 pip 在嘗試通過 HTTPS 安全協議 連接到 PyPI 官方服務器（pypi.org）時，連接被意外地關閉了。

那么，誰是中斷這個連接的“幕后黑手”呢？

在絕大多數情況下，“罪魁禍首”就是你系統中運行的網絡代理工具，例如本案例中的 Clash for Windows。

當你開啟了 Clash 的 System Proxy模式時，Clash 會嘗試接管系統中幾乎所有的網絡請求，包括 pip 的下載請求。但由于某些配置、防火墻或網絡環境的原因，代理軟件在處理 pip 發起的這個 SSL 加密連接時出現了問題，無法正確地轉發或完成 SSL 握手，最終導致連接被粗暴地中斷，從而拋出 SSLError。

三、解決方案

既然定位到了是系統代理的問題，我們就有多種解決方案，從簡單粗暴到一勞永逸，任君選擇。

方案一：暫時關閉系統代理（治標不治本）
這是最直接、最快速的解決方法，也是提問者最終采用的方法。

操作步驟：

打開你的代理工具，如 Clash for Windows。

找到 System Proxy 的開關。

暫時關閉它。如上圖所示，將綠色的開關點為灰色。

回到你的終端，重新執行 pip install 命令。

原理：
關閉系統代理后，pip 的網絡請求將不再經過 Clash，而是直接連接到 PyPI 服務器。沒有了中間的代理干擾，連接自然就恢復正常了。

最后安裝步驟安裝好模塊再打開選項就行~

方案二：曲線救國——更換 pip 下載源
如果你只是偶爾遇到這個問題，或者不想折騰代理設置，還有一個非常有效的辦法：更換為國內的鏡像源。國內鏡像源訪問速度快，且不需要通過代理。

操作步驟：
在 pip install 命令后加上 -i 參數，指定一個國內鏡像地址。

例如，使用清華大學的鏡像源：

pip install pycocotools -i https://pypi.tuna.tsinghua.edu.cn/simple

或者使用阿里云的鏡像源：

pip install pycocotools -i http://mirrors.aliyun.com/pypi/simple/

優點：
下載速度快，且能繞開代理問題。

缺點：
每次安裝都需要手動加上 -i 參數。當然，你也可以通過配置將其設為默認源，但這會讓你在需要從官方源下載某些特定包時遇到麻煩。

總結
pip install 遇到 SSLError: EOF occurred in violation of protocol 錯誤，99% 的情況是由于網絡代理工具干擾了正常的 HTTPS 連接。

最快的臨時解法：暫時關閉代理軟件的“系統代理”功能。

最推薦的永久解法：通過 pip config set global.proxy 命令，為 pip 單獨配置代理。

最有效的備用解法：使用 -i 參數更換為國內鏡像源進行下載。

希望這篇教程能幫助你解決這個惱人的網絡問題，讓你重新享受順滑的 pip install 體驗！如果覺得有用，歡迎點贊、收藏、轉發！