Docker 拉取映像總逾時？Windows 與 macOS 上讓 Docker Desktop 走 Clash 的步驟

為什麼「瀏覽器正常」不代表 docker pull 會自動走 Clash？

許多開發者已在本機執行 Clash（或相容核心用戶端），瀏覽器透過系統代理或 TUN 能上網，但一執行 docker pull、docker build，或在容器裡 apt update，卻出現連線逾時、TLS 握手卡住、或速度極慢。原因在於：Docker Desktop 的引擎與容器網路，預設不會自動繼承您為瀏覽器設定的同一條代理路徑。

實務上可拆成四層來想：（1）宿主機上的 Clash 是否在正確埠提供 HTTP／HTTPS 代理；（2）Docker Desktop 是否把該位址寫進「引擎／守護行程」可讀的代理設定；（3）Windows 若使用 WSL2 後端，虛擬環境與路由是否與 Clash 模式相容（必要時需搭配另一篇 WSL2 路由／MTU 排查）；（4）容器執行期與建置期是否另外帶入 HTTP_PROXY／HTTPS_PROXY。下面依序收斂，避免只改一處卻以為已全域生效。

步驟一：先對齊 Clash 的 HTTP 代理埠與略過清單

在設定 Docker 之前，請先確認 Clash 的混合埠（mixed-port）或獨立的 HTTP 埠數值。常見預設為本機 127.0.0.1:7890，但若您改過埠、或僅開啟 SOCKS，Docker 引擎透過 HTTP 代理連線時就會失敗。請在用戶端介面或設定檔確認「HTTP 代理」實際監聽位址。

同時檢查 略過（bypass） 或規則是否把映像倉庫網域誤判成直連：若節點對該網域品質不佳，可能出現「偶爾成功、多半逾時」的假性隨機。可暫時以較單純的規則組合對照，縮小是代理鏈路問題還是 DNS／節點問題。若尚未完成訂閱匯入，可先參考 全平台訂閱匯入教學，確保基礎設定可用。

步驟二：在 Docker Desktop 設定 HTTP／HTTPS 代理（Windows 與 macOS 共通）

開啟 Docker Desktop，進入 Settings（設定），尋找與 Proxies（代理）或資源／網路相關的區塊（不同版本選單名稱可能略有差異）。啟用手動代理後，將 HTTP 與 HTTPS 皆指向本機 Clash，例如：

http://127.0.0.1:7890
https://127.0.0.1:7890

重點是讓 Docker 引擎在拉取映像、存取映像倉庫 API 時走這條代理。設定完成後建議按下 Apply & Restart（套用並重新啟動），讓背景 VM 或守護行程重新載入。若僅改宿主機環境變數而未在 Docker Desktop 內填寫，常見現象仍是 docker pull 不走代理。

若您使用公司內部或區網的私有 映像倉庫，請一併設定 NO_PROXY／略過清單，避免私有網段流量被強制送往外部代理而失敗。格式通常為逗號分隔的主機名稱或 CIDR，實際欄位名稱依 Docker Desktop 版本為準。

步驟三：Windows 與 WSL2 後端——引擎在哪裡跑，代理就要跟到哪裡

在 Windows 上，Docker Desktop 預設使用 WSL2 作為後端時，Linux 引擎跑在微軟的虛擬環境中；您在 Windows「網際網路選項」裡設的系統代理，未必等同於引擎實際使用的網路堆疊。因此優先依賴上一節 Docker Desktop 內建的代理設定，而不是假設「開了系統代理就夠了」。

若您另外在 WSL 發行版內直接安裝 docker 用戶端並連到 Docker Desktop 的後端，或在 WSL 內執行建置指令，有時還需在 WSL 環境中設定 export HTTP_PROXY=http://127.0.0.1:7890 等變數（埠請替換為您的 Clash 實際埠）。此情況與「純 Windows 路徑執行 docker」略有不同，建議一次只改一種環境，避免 Windows 與 WSL 各有一套互相覆寫的代理值。

若完成代理設定後仍出現「僅 WSL 內異常慢、Windows 側正常」的斷裂感，可能已偏向路由或 MTU 層級，而非單純 HTTP 代理。此時可搭配 Windows 11＋WSL2 路由與 MTU 排查教學，先確認預設路由與介面度量，再回到 Docker 代理微調。

步驟四：macOS 上的補充：本機位址與 Docker 設定檔

在 macOS 上，Docker Desktop 同樣以虛擬化環境承載引擎；在 Docker Desktop 圖形介面填入 127.0.0.1:埠 通常即指向 Mac 本機的 Clash，與瀏覽器走同一個本機代理一致。若您使用命令列工具或 CI 腳本，亦可檢查使用者目錄下的 Docker 設定檔（常見為 ~/.docker/config.json）是否曾寫入舊的代理或認證資訊，必要時備份後清理再重試，以免與 Docker Desktop 新設定衝突。

少數情境下，容器內若要連回宿主機上的服務（例如本機 Clash），在 Docker Desktop 可使用 host.docker.internal 這類特殊主機名（依 Docker 版本與平台而定）。但對「容器內程式要經由代理上外網」而言，仍以設定 HTTP_PROXY 環境變數並指向可連線的代理位址為主；請以實際測試為準，不要混用未經驗證的捷徑。

步驟五：建置與執行容器時的環境變數

即使引擎已走代理，映像內執行的程式仍可能預設不使用系統代理。建置映像時可在 docker build 帶入：

docker build \
  --build-arg HTTP_PROXY=http://host.docker.internal:7890 \
  --build-arg HTTPS_PROXY=http://host.docker.internal:7890 \
  -t myimage:latest .

埠號請改為您的 Clash 埠。host.docker.internal 在 Docker Desktop（Windows／macOS）上常用於從容器連回宿主機；若您的環境不支援該名稱，可改為宿主機在 Docker 網橋上可達的閘道 IP，並以實測為準。

執行容器時，可使用 -e HTTP_PROXY=... 或在 docker-compose.yml 的 environment 區塊宣告，讓 apt、npm、pip 等工具在下載依賴時走代理。若僅設定引擎代理而未設定容器環境，仍會出現「pull 成功，但容器一啟動就連不上外網」的現象。

步驟六：映像倉庫與 Registry Mirror（選用）

若延遲來自公有映像倉庫的地理位置或頻寬，而非單純「無法連線」，除了代理之外，也可評估設定 registry mirror（映像快取／鏡像站）。此舉與 HTTP 代理不同：鏡像站是另一種拉取路徑，需信任來源並確認與您組織資安政策相容。代理與鏡像可並存，但請避免重複設定導致行為難以追蹤。

Clash 的 TUN 與「只設 HTTP 代理」的關係

若您習慣只開 TUN 而不開系統 HTTP 代理，Docker 引擎未必自動受益，因為引擎與映像倉庫的通訊仍以顯式 HTTP 代理設定或路由層接管為主。實務上常見做法是：同時在 Clash 開啟混合埠 HTTP 代理，並在 Docker Desktop 填寫同一埠；或確保 TUN 路由完整涵蓋 Docker 相關介面（進階且易與其他虛擬網卡互動，需謹慎）。關於 TUN 模式概念，可延伸閱讀 Clash TUN 模式完全指南。

檢查清單（建議順序）

• Clash：HTTP 代理埠是否為預期數值？規則是否誤傷映像倉庫網域？
• Docker Desktop：Proxies 是否已填 http(s)://127.0.0.1:埠 並套用重啟？
• NO_PROXY：私有倉庫或內網位址是否已略過？
• WSL2：症狀是否僅發生在子系統？若是，先對照路由／MTU 文再回頭看代理。
• 容器：docker build／執行時是否補上 HTTP_PROXY／HTTPS_PROXY？
• 驗證：改一項、重啟一次、再 docker pull hello-world 類小型映像測試。

結語

Docker Desktop 與瀏覽器不同，docker pull 是否順利，取決於引擎是否明確走 HTTP／HTTPS 代理、WSL2 後端網路是否健康，以及容器內是否另行需要代理環境變數。把四層分開排查，通常能快速分辨「設定沒生效」與「路由／MTU 類問題」，避免在錯誤層級反覆嘗試。

相較於零散複製指令，使用穩定的用戶端與清楚的分流設定，長期維護成本更低。若您希望從本站取得對應平台的 Clash 用戶端與教學起點，可先前往下載頁選擇系統版本，再依序完成訂閱與代理對齊。