執行 docker pull 時出現 Client.Timeout exceeded、TLS handshake timeout,或長時間停在下載圖層,不一定代表 Docker Hub 故障。常見原因是 Docker Engine 沒有使用 Clash 代理、代理位址只在終端機可用,或 Clash 規則把 Registry 請求送往直連。排查時要先分清楚「終端機」與「Docker daemon」:真正負責下載映像檔的通常是 daemon,單純在目前 shell 設定代理變數,不保證它也會走代理。本文會依序檢查代理設定、連線與規則,再用可重現的測試確認修復結果。

先判斷逾時發生在哪個環節

Docker Hub 拉取映像檔時,可能需要連線到多個服務:registry-1.docker.io 負責 Registry API,auth.docker.io 提供授權資訊,映像檔圖層則可能由 CDN 網域傳送。因此,瀏覽器能開啟 Docker Hub 首頁,並不表示 Docker 的整條下載鏈路都正常;某個授權或圖層網域被直連、DNS 解析錯誤,仍會讓整次拉取失敗。

先記下錯誤訊息中的主機名稱和階段。若錯誤包含 lookup、no such host,優先檢查 DNS;若出現 i/o timeout、context deadline exceeded,常見原因是路由、代理或防火牆;若是 unauthorized、denied,則應另查登入狀態、映像檔名稱或存取權限,單純更換節點通常無法解決。

先看請求由誰發出:docker pull 的下載流量通常由 Docker daemon 發出,而不是由目前的 shell 直接傳送。終端機的 HTTP_PROXY 設定與 Docker daemon 的代理設定是兩件事,排查時不要只確認其中一處。

確認 Clash 代理連接埠可用

先在 Clash Verge、Clash Verge Rev 或其他 Mihomo 用戶端確認核心正在執行,並查看 HTTP 或 mixed-port 的實際連接埠。常見預設值是 7890,但使用者可以自行修改;請以用戶端設定頁或 YAML 中的 port、mixed-port 為準。若啟用了系統代理,也不要因此假定 Docker daemon 已自動取得相同設定。

在執行 Docker 的主機上,先測試代理能否連到 Registry。以下命令中的連接埠請替換成你的 Clash HTTP/mixed-port:

透過本機 Clash 測試 Registry
curl -x http://127.0.0.1:7890 -I https://registry-1.docker.io/v2/

如果代理連線成功,Registry API 通常會回應 401 Unauthorized。這裡的 401 是預期結果,表示請求已抵達 Registry,只是測試請求沒有附上 Docker 認證資訊;它不是代理失敗。相反地,若看到連線被拒絕,請確認連接埠、Clash 核心狀態及 HTTP/mixed-port 類型;若一直等待後逾時,再檢查目前選取的節點和 Clash 日誌。

127.0.0.1 只代表目前命令所在的主機。若 Docker Engine 位於另一台主機、虛擬機或遠端環境,就必須使用 Docker Engine 能連到的代理位址。在 Linux 上,daemon 通常不能透過自己的 loopback 位址連到桌面環境中的 Clash;在 Docker Desktop 上,代理設定一般由 Desktop 管理,也可依其網路環境使用 host.docker.internal。不要直接把 127.0.0.1 貼到所有環境而不驗證。

為 Docker daemon 設定代理

在 Linux 主機上以 systemd 執行 Docker Engine 時,可建立 daemon 的 systemd drop-in 設定。代理網址要填入 Docker daemon 可達的主機位址;若 Clash 只監聽在主機的 loopback,請先確認 daemon 所在的網路環境是否能連到它。變更設定後需要重新載入 systemd 並重啟 Docker,修改 shell 的環境變數並不會取代這個步驟。

Linux Docker daemon 代理設定
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

在編輯器中加入下列內容,將 192.168.1.10 替換成 daemon 能連線到的 Clash 主機位址,並依實際情況調整連接埠:

http-proxy.conf 範例
[Service]
Environment="HTTP_PROXY=http://192.168.1.10:7890"
Environment="HTTPS_PROXY=http://192.168.1.10:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

儲存後執行以下命令,再檢查 Docker 是否已讀入代理變數:

重新載入並檢查 Docker 服務
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl show --property=Environment docker

使用 Docker Desktop 的 macOS 或 Windows 使用者,應優先檢查 Docker Desktop 的 Proxy 設定頁,確認 HTTP/HTTPS 代理指向可用的 Clash 位址,套用後依提示重新啟動 Desktop。不同版本的設定選項可能不同;若設定由 Desktop 管理,不建議同時用多種互相衝突的方式覆寫 daemon 代理。Windows PowerShell 中使用的 $env:HTTPS_PROXY 只會影響該 PowerShell 工作階段與其子程序,不能單獨證明 Docker Desktop 的映像檔下載流量已套用此值。

還要區分 daemon 拉取映像檔與建置容器時的代理需求。Docker CLI 設定檔中的 proxies 可為建置或執行中的容器提供代理參數,但它不等同於 Docker daemon 的 Registry 代理設定。若 docker pull 仍逾時,應先確認 Docker Desktop 或 systemd daemon 本身的代理,而不是只修改建置容器用的設定。

檢查 Clash 規則、節點與監聽位址

代理位址可連通後,再確認 Docker Hub 相關請求確實走代理。Clash 的規則模式可能依網域、IP 或規則提供者決定路由;若 Registry 或授權網域命中直連規則,shell 透過代理成功也不代表 Docker 的實際請求會採用同一路徑。開啟 Clash 的連線記錄,在執行 docker pull 時觀察相關連線,確認命中的規則與最後使用的策略組。

排查時可留意下列網域:registry-1.docker.io、auth.docker.io,以及錯誤訊息中顯示的圖層下載主機。CDN 網域可能隨服務調整,不宜只憑一個固定網域清單判斷是否完整。若某個下載請求走了直連,可在 Clash 中修正相應規則或策略,再重新測試;不要為了方便直接改動整份設定檔的所有流量策略。

使用區域網路代理時注意監聽範圍:若 Docker daemon 需要透過區域網路連到 Clash,Clash 必須監聽在 daemon 可達的介面,且防火牆允許對應連接埠。開啟 allow-lan 或綁定 0.0.0.0 可能讓區域網路中的其他裝置也能使用代理;只在可信任網路中設定,並限制存取範圍,避免將代理服務暴露到不必要的網路。

如果連線記錄顯示請求走了代理,但仍然失敗,可以暫時切換到另一個可用節點,確認是否為單一出口、DNS 或上游連線問題。比較節點時,應保持代理位址和 Docker 設定不變;一次只改一項,才容易判斷是哪個因素造成差異。若所有節點都失敗而直連測試正常,回頭檢查代理格式、daemon 是否信任該代理,以及代理是否允許 HTTPS CONNECT。

用 Docker 指令驗證修復結果

修正設定並重新啟動 Docker 後,先重新執行 Registry 的 curl 測試,再確認 daemon 服務的代理設定已生效。接著使用小型、常見的公開映像檔進行拉取測試:

驗證 Docker Hub 拉取
docker pull hello-world
docker run --rm hello-world

若拉取成功,代表 Docker Engine 已能完成 Registry 存取與映像檔下載;執行容器則可再確認映像檔能正常使用。若仍失敗,請記下錯誤發生的網域和時間,對照 Clash 連線記錄與 Docker daemon 日誌。Linux 可使用 journalctl -u docker --since "10 minutes ago" 查看近期服務訊息;Docker Desktop 則可透過疑難排解或診斷功能查看日誌。

測試結果較可能的原因下一步檢查
curl 顯示連線被拒絕代理連接埠錯誤或未監聽確認 Clash 核心狀態與 HTTP/mixed-port
curl 回應 401,Docker 仍逾時daemon 沒有套用代理,或下載網域路由不同檢查 daemon 代理與 Clash 連線記錄
Registry API 可達,圖層下載失敗CDN 路由、節點出口或防火牆問題檢查錯誤中的下載主機並測試其他節點
回應 unauthorized 或 denied認證、映像名稱或權限問題確認映像名稱、標籤及 Docker Hub 登入狀態

若設定曾反覆修改,建議先記錄目前的代理位址、Clash 節點與規則,再只保留一套明確的 daemon 代理設定,避免舊的 systemd drop-in、Docker Desktop 設定與 shell 變數互相混淆。完成測試後,也可拉取原本失敗的映像檔,確認實際工作負載所需的倉庫與圖層都能下載。

常見問題 FAQ

設定了終端機代理,為什麼 docker pull 還是逾時?

因為拉取映像檔通常由 Docker daemon 發出,而終端機的代理變數只對該工作階段及其子程序生效。請另外設定 Docker Desktop 的代理,或為 Linux 上的 Docker systemd 服務設定代理,並重新啟動 Docker 後再測試。

curl 回應 401 是不是代表 Clash 沒有代理成功?

不一定。對 https://registry-1.docker.io/v2/ 發出未附認證的請求時,401 通常是正常的 Registry 回應,表示連線已抵達服務。若要確認 Docker 拉取流程,仍需執行 docker pull,並觀察 Clash 是否記錄了相關連線。

Docker Desktop 可以直接使用 127.0.0.1:7890 嗎?

要看 Desktop 的代理設定與執行環境,不能一概而論。容器或虛擬化環境中的 loopback 可能指向它自身,而不是主機上的 Clash。請依 Docker Desktop 的代理設定方式設定,並以 Registry 測試與實際拉取結果驗證。

代理看起來正常,但映像檔仍拉不下來怎麼辦?

對照 Docker 錯誤中的目標網域與 Clash 連線記錄,確認 Registry、授權及圖層下載請求是否都能連線。若錯誤是權限或認證問題,檢查映像名稱、標籤和登入狀態;若是逾時,則依序檢查 daemon 代理、命中規則、節點出口與防火牆。

Docker Hub 下載逾時的排查重點,是讓「真正執行拉取的 Docker daemon」能連到 Clash,並確認 Registry、授權與圖層請求都走到預期路徑。從代理連接埠開始,逐項驗證 daemon 設定、Clash 規則與節點,再以 curl 和 docker pull hello-world 作為檢查依據,比反覆更換設定更容易找到根因。

立即開始

用 Clash 掌控您的流量

支援 Windows、macOS、Linux、Android 與 iOS,靈活規則,開箱即用。

免費下載 查看設定指南 →