程式碼抓取卡住、容器映像檔拉不下來、套件安裝逾時，通常不只是「網路速度不夠快」這麼單純。GitHub、Docker Registry、npm、PyPI 以及各種 API 服務，可能使用不同的網域、DNS、TLS 連線方式與長連線策略；瀏覽器能開啟某個網站，也不代表 Git、Docker 或終端機中的套件管理器一定能正常工作。

這篇指南依照開發者每天可能經歷的工作流程，整理 GitHub 程式碼抓取、Docker 映像檔下載、npm 與 pip 套件安裝，以及 API 連線的設定方式。核心原則是先判斷問題位於 DNS、TCP、TLS、代理分流還是遠端服務本身，再選擇全域代理、規則代理或只為特定工具設定代理。這樣既能改善連線穩定性，也能避免把本地服務、公司內網與容器內部請求不必要地送到遠端線路。

開發者網路加速的基本判斷

開發工具的網路問題大致可以分成四類。第一類是名稱解析失敗，例如 DNS 無法找到 GitHub、Registry 或套件來源的位址；第二類是連線建立緩慢，TCP 或 UDP 路徑受到當前網路環境影響；第三類是 TLS 握手或長連線中斷，常見於大型檔案、串流下載與需要持續連線的 API；第四類是工具本身沒有使用你以為已經開啟的代理。

因此，不建議一開始就反覆更換節點。應先用最小化測試確認問題層級。瀏覽器測試只能說明瀏覽器的請求結果，不能代替 Git、Docker daemon 或容器內部的測試。相反地，命令列工具回報的錯誤訊息通常更有價值，例如「Could not resolve host」偏向 DNS 問題，「Connection timed out」可能涉及路由或防火牆，「SSL certificate problem」則應優先檢查系統時間、憑證鏈與企業中間人代理。

5

本文工作流程

4

主要故障層級

2

常見代理方向

1

先做的原則

代理方向通常有兩種。第一種是由 VPN 用戶端或相容客戶端建立系統層級的通道，再用規則模式決定哪些網域經過代理；第二種是讓特定命令列工具讀取 HTTP、HTTPS 或 SOCKS5 代理。前者設定較集中，適合多種工具都需要使用同一套分流規則；後者控制範圍較小，適合只處理 GitHub、Docker Registry 或套件安裝。

判斷重點： 不要把「瀏覽器可以開啟」當成「所有開發工具都已經走代理」。每個工具都要確認代理來源、DNS 行為與實際出口。

GitHub 與 Git：先處理抓取和推送

GitHub 相關問題通常分成網頁存取、Git over HTTPS、Git over SSH，以及大型儲存庫或子模組下載。網頁能開不代表 Git clone 一定成功，因為 Git 可能沒有繼承系統代理，SSH 也不會自動使用瀏覽器的 HTTP 代理。

Git over HTTPS 的代理設定

如果儲存庫使用 HTTPS 位址，可以先讓 Git 讀取專用的 HTTP 代理。以下設定只會影響 Git，不會改變其他應用程式：

git config --global http.proxy http://127.0.0.1:連接埠
git config --global https.proxy http://127.0.0.1:連接埠

git config --global --get http.proxy
git config --global --get https.proxy

實際連接埠應以你使用的 VPN 用戶端或相容客戶端顯示內容為準，不要直接照抄他人設定。若工具提供 SOCKS5 入口，也可以使用相應的代理格式，但要確認 Git 版本與本機代理程式是否支援該方式。代理設定完成後，先用小型公開儲存庫測試，再處理大型專案，這樣更容易判斷是權限問題還是網路問題。

若不希望長期保留代理，可以只為單次命令設定：

git -c http.proxy=http://127.0.0.1:連接埠 \
    -c https.proxy=http://127.0.0.1:連接埠 \
    clone https://github.com/組織/專案.git

使用完畢後，若要移除全域設定，可執行：

git config --global --unset http.proxy
git config --global --unset https.proxy

SSH、子模組與大型專案

SSH 連線與 HTTPS 的代理設定不同。若專案使用 SSH 位址，請先確認本地 SSH 金鑰、代理轉送與遠端主機驗證，不要因為連線困難就關閉主機金鑰檢查。若所在網路不允許直接建立 SSH 連線，可以考慮改用 HTTPS，或依照受信任的網路管理規範設定 SSH 代理跳轉。

子模組是另一個常見陷阱。主專案 clone 成功後，子模組可能使用另一個 HTTPS 或 SSH 位址，導致後續初始化失敗。可以先查看設定檔中的子模組來源，再逐一確認它們是否能用同一種代理方式存取。大型儲存庫若包含 Git LFS，也要另外確認 LFS 是否繼承 Git 的代理設定；只配置 Git 本身，不一定能涵蓋所有大型檔案請求。

  • ✅ 先確認遠端位址是 HTTPS 還是 SSH，再選擇代理設定方式。
  • ✅ 檢查 Git、Git LFS 與子模組是否使用相同的網路路徑。
  • ✅ 只為 Git 設定代理時，優先採用命令列單次設定降低影響範圍。
  • ❌ 不要用關閉 TLS 驗證或忽略主機金鑰的方式掩蓋連線問題。

Docker：區分 Docker CLI 與 daemon

Docker 最容易讓人誤判的地方，是執行命令的 Docker CLI 與真正下載映像檔的 Docker daemon 可能不在同一個環境。你在終端機中設定了代理，並不代表 Docker daemon 也能使用它。尤其在 Linux 上，daemon 常以 systemd 服務執行；在 Windows 或 macOS 上，Docker Desktop 也有自己的虛擬化環境與網路設定。

先用簡單命令確認目前環境：

docker version
docker info
docker pull 映像檔:標籤

如果錯誤出現在拉取映像檔階段，應優先檢查 daemon 的 DNS、代理與 Registry 存取，而不是隻修改 Shell 的 HTTP_PROXY。對 systemd 管理的 Docker，可以依照發行版文件建立服務覆寫設定，並在變更後重新載入服務。設定內容應由管理員依照實際代理位址填寫，且要明確列出不應經過代理的本機網段。

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:連接埠"
Environment="HTTPS_PROXY=http://127.0.0.1:連接埠"
Environment="NO_PROXY=localhost,127.0.0.1,.local"

# 儲存後依系統文件重新載入並重啟 Docker 服務

Docker Desktop 使用者則應在應用程式的網路或代理設定中檢查，而不是隻修改終端機環境變數。若公司環境使用自訂憑證或 TLS 檢查，必須按照管理政策將受信任的 CA 憑證配置到正確位置；不要用關閉安全驗證的方式解決憑證錯誤。

映像檔拉取與建置階段的差異

docker pull 主要由 daemon 存取 Registry；docker build 則可能同時涉及基礎映像檔、Dockerfile 中的套件下載、Git URL 與多階段建置。即使基礎映像檔成功拉取，建置階段的 RUN npm install 或 RUN pip install 仍可能因容器內的 DNS 與代理設定不同而失敗。

若建置需要使用外部套件來源，應明確設計代理傳入方式，並避免把帳號、密碼或訂閱連結直接寫入 Dockerfile。可以使用建置參數或建置環境提供短期設定，但仍要確認敏感資訊不會出現在映像檔 layer、建置記錄或快取中。完成測試後，清理不再需要的代理環境變數，避免應用程式執行階段意外沿用建置代理。

操作 主要請求來源 優先檢查 常見誤區
docker pull Docker daemon daemon 代理、DNS、Registry 憑證 只設定終端機代理
docker build daemon 與建置容器 基礎映像檔、Dockerfile、容器內 DNS 以為 pull 成功就代表 RUN 一定成功
docker push Docker daemon Registry 權限、登入狀態、上傳路徑 忽略上傳方向的代理限制

npm 與 pip：套件來源、快取與逾時

套件管理器的問題不一定需要全域加速。npm 會讀取 registry 設定、環境變數與使用者設定檔；pip 則可能受到 index URL、憑證、代理與快取影響。先確認目前使用的套件來源，再決定是調整來源、使用代理，還是修復本地憑證。

npm 的 registry 與代理檢查

可以先查看 npm 的有效設定：

npm config get registry
npm config get proxy
npm config get https-proxy
npm cache verify

如果套件來源本身可用，但當前網路無法穩定連線，可以為 npm 指定與其他工具一致的代理。若只需要暫時測試，建議使用命令列參數或環境變數，而不是立即修改所有專案的設定。若專案包含 lockfile，切換 registry 後要注意套件解析結果、私有套件權限與完整性校驗，不要為了速度刪除 lockfile。

npm 安裝逾時也可能與某個套件的 postinstall 腳本、Git 依賴或二進位檔下載有關。此時應查看詳細記錄，確認卡住的是 registry 請求、Git 下載，還是套件安裝腳本中的其他 API。只增加 timeout 可能讓等待時間更長，卻不會修復錯誤的代理或 DNS。

pip 的 index、憑證與代理

pip 可以透過命令列、設定檔或環境變數指定套件來源。排查時先查看目前設定，尤其要留意專案虛擬環境與系統 Python 是否讀取不同的設定檔。若使用 HTTPS 套件來源，請保留憑證驗證，並確認系統 CA 憑證已更新。

python -m pip config list
python -m pip install --upgrade pip
python -m pip install 套件名稱 --timeout 時間

使用 python -m pip 通常比直接輸入 pip 更容易確認套件管理器屬於哪個 Python 環境。若下載速度不穩定，先清楚區分公共套件來源、公司私有 Registry 與本地快取的角色。私有套件來源若需要 Token，請放在權限受控的設定中，不要把憑證提交到 Git 儲存庫或寫入 Dockerfile。

  • ✅ 先記錄 npm registry 或 pip index，再判斷是否需要更換來源。
  • ✅ 使用虛擬環境與 lockfile，讓加速設定不改變依賴版本。
  • ✅ 對私有套件與 Token 使用最小權限，並避免出現在終端機共享記錄。
  • ❌ 不要把關閉 SSL 驗證當成套件安裝逾時的通用解法。

API 連線：從命令列測到應用程式

API 常見問題包括 DNS 解析不一致、SNI 或 TLS 握手失敗、代理未被 SDK 繼承、長連線中斷，以及本地時間不正確導致簽名失效。排查時不要只在瀏覽器打開 API 網址，應使用與應用程式接近的請求方式測試 HTTP 方法、標頭、重導向與回應內容。

可先用 curl 觀察名稱解析、TLS 與 HTTP 回應：

curl -I https://api.example.com
curl -v https://api.example.com/health
curl --proxy http://127.0.0.1:連接埠 https://api.example.com/health

如果直接連線失敗、透過代理成功，問題可能位於本地路徑或 DNS；如果兩者都失敗，則要檢查 API 位址、憑證、權限與服務狀態；如果命令列成功但程式失敗，應回到 SDK 的代理參數、環境變數與連線池設定。Node.js、Python、Go 等語言的 HTTP 函式庫對代理的支援方式不同，不能假定所有 SDK 都會自動讀取系統代理。

對 API 金鑰、Bearer Token、Cookie 與訂閱連結要採取同樣的安全標準。不要將完整請求內容貼到公開工單或聊天羣組，也不要把含有敏感標頭的 verbose log 直接提交到儲存庫。測試時可先使用健康檢查端點或不含敏感參數的請求，再逐步加入認證與業務參數。

一套可重複的實作流程

下面是一個適合 Windows、macOS、Linux，以及使用官方 VPN 用戶端或 Clash Verge、sing-box、Shadowrocket 等相容客戶端的排查順序。不同客戶端對 HTTP、SOCKS5、TUN 與規則模式的名稱可能不同，請以實際介面為準。這裡的重點不是固定某個節點，而是讓測試結果可以重現。

  1. 確認代理入口。 記下本地 HTTP 或 SOCKS5 代理的位址與連接埠，確認客戶端目前確實處於已連線狀態。
  2. 測試名稱解析。 分別測試 GitHub、Docker Registry、npm 或 PyPI 使用的網域，記錄錯誤是解析失敗還是連線逾時。
  3. 測試最小 HTTP 請求。 使用 curl 先確認 API 或網站能否建立 HTTPS 連線，再測試完整下載。
  4. 單獨配置 Git。 先處理 Git over HTTPS，確認 clone 能完成，再檢查子模組與 Git LFS。
  5. 配置 Docker daemon。 不要只改 Shell 環境變數，確認 daemon 或 Docker Desktop 的代理已生效，然後測試 pull。
  6. 檢查套件管理器。 確認 npm registry、pip index、私有來源與憑證設定，避免把所有逾時都歸因於速度。
  7. 縮小分流範圍。 如果只有特定開發工具需要代理，優先採用工具層設定；本地服務、內網位址與資料庫應加入適當的直連規則。
  8. 清除臨時設定。 測試完成後移除不再需要的全域代理、Shell 變數與建置參數，避免後續在不同網路環境中產生難以追蹤的錯誤。

若使用訂閱連結匯入節點，建議先在用戶端中更新訂閱，再挑選適合的線路與協定。Shadowsocks、VMess、Trojan、Hysteria2 與 WireGuard 的握手和傳輸特性不同，某一協定在行動網路表現較好，不代表在公司或校園網路也一定相同。若需要更細緻的應用程式分流，可在支援規則的相容客戶端中，將 GitHub、Registry、套件來源與 API 分別納入規則，但不要把所有網域一概送往代理。

實作結論： 先用 curl 確認路徑，再依序處理 Git、Docker、npm、pip 與 API；每完成一層就測試一次，能比同時修改所有設定更快定位問題。

安全性、分流與長期維護

開發者網路加速的目標不是讓所有流量都經過同一條通道，而是在需要的地方改善連線，同時保持本地服務與敏感資料的控制範圍。全域模式雖然容易理解，但可能讓雲端同步、公司內網、資料庫連線與本機開發服務一起受到代理影響；規則模式較靈活，卻需要定期檢查規則是否過期或誤判。

建議將以下內容視為日常自查項目：代理與訂閱連結只保存在受控位置；不同工具不共用不必要的帳號 Token；Docker 建置記錄不包含祕密；Git 不關閉 SSL 驗證；私有 npm 或 pip 來源使用最小權限；API log 遮蔽授權標頭與個人資料；更換網路或 VPN 線路後，重新確認 DNS、出口位址與本地服務是否仍正常。

如果連線突然變慢，先回到最後一次成功的設定，逐項比較代理入口、分流規則、協定、DNS 與工具設定。不要同時開啟兩個會建立 TUN 或系統代理的客戶端，也不要在沒有記錄變更內容的情況下反覆修改 Docker daemon、npm registry 與 pip index。保留一份可還原的設定，通常比追求單次峯值速度更有價值。

最後檢查 開發環境恢復正常後，請再測一次程式碼抓取、映像檔拉取、套件安裝與 API 請求，確認它們使用的是預期路徑；若只測瀏覽器，仍可能遺漏 Docker daemon 或容器內部的問題。