開發者 GitHub、Docker、npm 高速連線完整設定

開發者網路為什麼要分流設定

GitHub 工作流程至少包含網頁、Git over HTTPS、Git over SSH、Release 檔案、套件下載與容器映像檔等不同連線。這些連線可能由不同程序發起，也可能使用不同的 DNS 解析、TLS 驗證與代理支援方式。把瀏覽器流量切換到代理後，Git CLI 不一定會讀取瀏覽器的設定；Docker 的背景服務更可能在另一個使用者、另一個服務環境中執行。

因此，第一步應先列出開發環境中的實際目的地。例如，公開程式碼儲存庫、容器映像檔來源、npm registry、Python package index 和 CI 的依賴下載屬於外部資源；公司 GitLab、內網 API、資料庫、localhost 和區域網路服務則通常應維持直連。若所有流量都強制代理，內部網域可能無法解析，或讓本地測試服務受到不必要的路由影響。

選擇客戶端時，Windows、macOS、Linux 可優先考慮能匯入訂閱連結、支援規則分流並提供本機 HTTP 或 SOCKS 代理埠的工具；Android 與 iOS 則適合使用相容的官方客戶端或第三方代理客戶端。Clash Verge、sing-box、Shadowrocket 等工具的設定格式和支援協定並不完全相同，匯入前應確認訂閱內容是否相容。Shadowsocks、VMess、Trojan、Hysteria2 與 WireGuard 的連線模型不同，不能只看節點名稱判斷是否可用。

• ✅ 先確認問題發生在瀏覽器、Git、Docker、套件管理器或 CI 的哪一層。
• ✅ 讓公開依賴來源依規則使用代理，內部服務與本機位址保留直連。
• ✅ 匯入訂閱後核對協定與客戶端支援範圍，再進行工具設定。
• ❌ 不要因為瀏覽器能開啟 GitHub，就假定所有開發工具都已經套用代理。
• ❌ 不要把完整訂閱連結、存取權杖或 CI 機密寫入公開設定檔。

Git 與 GitHub代理設定方法

Git over HTTPS 是最容易透過 HTTP 代理處理的方式。可以先在目前終端機工作階段設定 HTTP_PROXY 與 HTTPS_PROXY，再執行 clone、fetch 或 push。這種方式適合暫時測試，關閉終端機後設定通常不會保留。若希望 Git 長期使用代理，也可以透過 Git 自身的設定項目指定代理。

export HTTPS_PROXY=http://127.0.0.1:PORT
export HTTP_PROXY=http://127.0.0.1:PORT
git config --global http.proxy "$HTTP_PROXY"
git config --global https.proxy "$HTTPS_PROXY"

上面的 PORT 必須替換為本機客戶端實際提供的 HTTP 代理埠，不能直接照抄。Windows PowerShell 可使用 $env:HTTPS_PROXY 與 $env:HTTP_PROXY 設定目前工作階段；如果使用 GUI 客戶端，則應在其代理設定中確認 HTTP 與 SOCKS 監聽埠的名稱。HTTP 代理和 SOCKS 代理不是同一種輸入格式，若客戶端只提供 SOCKS，Git 的支援方式會取決於版本與本機轉接工具，不宜任意把 socks5:// 填入所有欄位。

Git over SSH 的設定則不同。SSH 不會自動讀取 Git 的 http.proxy，需要在 SSH 設定中指定 ProxyCommand，或改用 Git over HTTPS。若只是要拉取公開倉庫，HTTPS 通常較容易管理；若工作流程必須使用 SSH key，則應單獨測試 SSH 主機連線，並確認代理命令不會影響其他 SSH 主機。

git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global --get-regexp 'http.*proxy'

排查時可先查看目前 Git 是否存在殘留代理。某些網路錯誤其實來自過期的本機埠、錯誤的代理類型或全域設定覆蓋了專案設定。測試完成後，如果需要恢復直連，應移除代理，而不是隻關閉客戶端。對公司內部網域，也可以使用 Git 的條件式設定，讓特定主機採用不同代理策略，避免外部和內部倉庫互相干擾。

Docker 映像檔與 daemon 分開處理

Docker 最常見的誤區，是隻在 shell 中設定代理，卻忘記實際下載映像檔的是 Docker daemon。Docker CLI 負責接收命令，daemon 才負責與 registry 通訊、拉取 layer、建立容器及執行部分建置工作。若 daemon 是由系統服務管理，它可能看不到目前使用者的 HTTP_PROXY；若使用 Docker Desktop，則應在 Desktop 的設定頁處理引擎代理，而不是隻修改終端機設定。

動手設定前，先區分兩種需求。第一種是 Docker CLI、BuildKit 或 daemon 透過代理連到外部 registry；第二種是建置過程中的 RUN 指令需要下載 apt、npm、pip 等依賴。前者影響 Docker 服務本身，後者還涉及建置容器內的環境變數。即使 docker pull 成功，Dockerfile 裡的套件下載仍可能因為沒有代理而失敗。

1. 確認客戶端已啟動，並記下本機 HTTP 代理埠，不要混用 SOCKS 埠。
2. 在 Docker Desktop 或 Docker daemon 的服務設定中填入代理，完成後重新啟動服務。
3. 使用公開且可信的映像檔進行拉取測試，觀察錯誤是 DNS、TLS、認證還是代理拒絕。
4. 若建置步驟仍失敗，再為 BuildKit 或建置階段傳入必要的代理環境。
5. 建置完成後檢查映像層和日誌，確認沒有把代理帳密寫入 Dockerfile 或鏡像層。

docker info
docker pull IMAGE_NAME
docker build --progress=plain -t local-test .

IMAGE_NAME 是需要測試的映像檔名稱，這些命令本身不代表任何特定 registry 一定可用。若使用 registry mirror，應確認鏡像來源的可信度、同步範圍與認證方式；鏡像站不是所有映像檔的永久替代品，也不應為了速度而忽略簽章、版本標籤和供應鏈檢查。企業環境還要注意 daemon 的憑證、代理白名單與防火牆政策。

npm 與 pip套件下載的穩定設定

npm 和 pip 通常從 registry 或 package index 取得大量小檔案，對 DNS、TLS、連線重試和代理相容性都比較敏感。最簡單的測試方式是先在目前終端機設定 HTTP_PROXY 和 HTTPS_PROXY，再執行套件管理器的查詢或安裝命令。確認代理確實有效後，再決定要寫入使用者層級設定，或只在特定專案與建置環境中使用。

npm config set proxy http://127.0.0.1:PORT
npm config set https-proxy http://127.0.0.1:PORT
npm config get registry
pip config list
python -m pip install --proxy http://127.0.0.1:PORT PACKAGE_NAME

PACKAGE_NAME 和 PORT 都是示意值，應按照實際套件和本機代理埠替換。npm 的 registry 設定決定套件索引來源，代理設定則決定連線如何出去，兩者不能混為一談。若公司使用內部 registry，應把公開套件代理和內部套件來源分開管理，避免為了處理一個來源而讓另一個來源失效。

pip 的設定可能來自命令列、環境變數、使用者設定檔、虛擬環境啟動腳本或 CI 變數。多層設定同時存在時，最容易出現「本機可以、腳本不行」的情況。排查時先列出目前生效的設定，再逐項確認 index URL、trusted host、憑證和代理是否由其他設定覆蓋。除非確定 TLS 憑證問題且理解風險，否則不要以停用憑證驗證作為快速解法。

• ✅ 將 npm registry、pip index 和代理埠分開確認。
• ✅ 依專案需要決定全域設定或單次命令設定，避免影響其他工作。
• ✅ 私有套件使用專用憑據，並透過祕密管理機制注入。
• ✅ 安裝失敗時記錄完整錯誤類型，但移除網址中的權杖與帳密。
• ❌ 不要把代理密碼、私有 registry token 或 pip 設定檔提交到程式碼儲存庫。

CI 建置如何避免本機與流水線不一致

CI 的執行環境可能是雲端 runner、自架 runner、容器或短期建立的虛擬機器。它們和開發者電腦的差異，不只在作業系統，也包括 DNS、憑證、環境變數、Docker daemon 位置與祕密管理方式。當本機 Git、npm、pip 都能工作，CI 卻在 checkout 或 install 階段失敗時，應先確認 runner 是否真的能到達所需外部來源，而不是立即修改依賴版本。

CI 中可以透過祕密變數注入 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。NO_PROXY 應放入 localhost、內部網域、服務名稱或私有網路位址，具體格式要依 runner 的作業系統和工具支援而定。代理網址若含有特殊字元，必須正確轉義；日誌輸出也要確認不會回顯完整環境變數。

export HTTP_PROXY="$CI_HTTP_PROXY"
export HTTPS_PROXY="$CI_HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example"
git clone "$REPOSITORY_URL"
npm ci
python -m pip install -r requirements.txt

如果 CI 需要建置 Docker 映像檔，還要區分 runner 容器、Docker CLI、Docker daemon 和建置容器四個層次。代理只傳給其中一層，其他層仍可能無法下載基礎映像或套件。更安全的做法是使用 runner 平台提供的祕密變數、短期憑據和受控配置，避免把代理帳密放在 YAML、Dockerfile、命令列參數或快取內容中。

快取可以減少重複下載，但不能取代正確的網路設定。快取內容需要有清楚的權限範圍與失效策略，私有套件和公開套件也不宜不加區分地共用。若某個 job 成功而另一個 job 失敗，應比較它們使用的 runner、容器映像、工作目錄、環境變數與代理設定，逐步縮小差異。

方案選擇與完整排查清單

開發者應按照流量型態和裝置數量選擇方案，而不是隻看單一下載速度。日常以 Git、npm、pip 為主，應先確認穩定的代理連線與分流能力；經常拉取容器映像、建立多個專案或在多台裝置間工作，則要留意流量額度是否適合。月訂閱包含 ¥9.9/月 60GB、¥18/月 250GB、¥28/月 500GB，流量按開通日每月重置；中途升級差價折算成剩餘天數。若流量使用時間不固定，也可以考慮用完為止、永久不過期的流量包：¥158/300GB、¥358/1000GB、¥658/3000GB。

這些方案都支援 Windows、macOS、iOS、Android 和 Linux，且同時線上設備數不限台數。節點覆蓋 110+ 國家、240+ 線路，實際選擇時仍應依目的地、連線協定和當前網路環境測試。若只需要開發工具的外部依賴流量，規則分流通常比所有應用程式都走代理更容易維護；若使用共享網路或需要多個工具保持一致，則可先使用全域模式確認問題來源，再切回規則模式。

當連線失敗時，可以按照以下順序處理：先關閉其他代理客戶端，避免多個虛擬網路介面互相搶路由；再確認目前客戶端的訂閱已更新且節點狀態正常；接著檢查系統時間、DNS、代理協定和本機監聽埠；最後才逐一檢查 Git、Docker、npm、pip 的專屬設定。若只有某個工具失敗，通常優先查看該工具的代理設定，而不是反覆切換所有節點。

如果需要重新設定，可以參考本站的查看教程，並依客戶端平台選擇 Windows、macOS、Linux、Android 或 iOS 的匯入方式。需要比較不同地區的線路時，可查看線路資訊；連線後則應使用工具自己的錯誤輸出、Git verbose 記錄或 Docker 詳細日誌判斷問題，不要只以瀏覽器頁面能否開啟作為唯一標準。