開發者 GitHub、Docker 拉取太慢？從套件安裝到 CI 的加⁠速攻略

先辨認是哪個下載環節變慢

先記下操作、工具、錯誤訊息與發生時間，並觀察停滯發生在連線建立、驗證、下載內容，還是解壓縮與編譯階段。Git clone 卡在建立連線，可能要檢查 DNS、代理或遠端主機連線；已開始下載但速度忽快忽慢，可能涉及傳輸路徑或本地網路；下載完成後長時間沒有進度，則也可能是磁碟 I/O、解壓縮或套件安裝腳本在執行。

同一項操作可用另一個網路環境或另一台設備做對照，但一次只改一個條件。先確認瀏覽器與命令列工具是否都受影響，再比較 Git、Docker、npm 或 pip 的結果。若只有某一個工具失敗，應優先檢查該工具自己的代理設定，而不是直接推斷整條線路不可用。

GitHub 的網頁、Git 傳輸、Release 附件、Git LFS 檔案和程式碼封存檔，可能涉及不同的請求或下載來源。Docker 拉取映像檔也不只下載一個檔案，通常會先取得映像資訊，再分別下載多個 layer。因而，頁面能載入或映像名稱能搜尋到，都不能證明後續每個下載請求都已順利完成。

• ✅ 記錄是哪個命令、哪個套件或映像，以及停在哪個階段。
• ✅ 區分連線錯誤、驗證錯誤、下載中斷與本機建置耗時。
• ✅ 比較瀏覽器和命令列工具，確認問題是否只出現在特定程式。
• ❌ 不要只因為下載慢，就立刻更換套件來源或停用安全檢查。

GitHub 與 Git：確認傳輸方式和代理

GitHub 網頁存取正常，但 git clone 或 git fetch 失敗時，先確認遠端網址使用 HTTPS 還是 SSH。兩者的代理設定方式不同：為瀏覽器配置系統代理，不會自動讓所有 Git 傳輸遵循代理；SSH 連線也不一定會讀取 HTTP 代理設定。檢查遠端網址、DNS 解析與用戶端的錯誤訊息，才能決定下一步要查哪個設定。

若使用本機代理，Git 的 HTTP 代理可以透過設定明確指定。以下的位址和連接埠只是格式示意，應換成可信任用戶端實際提供的本機監聽設定；不要直接照抄不存在的連接埠。若需要先做短時間測試，可只在目前終端機設定代理環境變數，測試後關閉該終端機即可避免設定長期殘留。

git config --global http.proxy http://127.0.0.1:PORT
git config --global --get http.proxy
git config --global --unset http.proxy

使用全域設定前，先確認它會影響哪些工作目錄和遠端主機。如果只想讓 GitHub 的 HTTPS 傳輸使用代理，可考慮採用 Git 支援的主機範圍設定，而不是讓所有 Git 遠端都套用相同規則。完成測試後檢查設定是否仍然存在；在共用電腦、公司設備或自動化執行環境上，尤其要避免留下含有個人帳號資訊的代理設定。

如果 Git clone 成功，但 Release 附件、子模組或 LFS 檔案仍然失敗，應把它們視為不同的檢查對象。逐一查看錯誤中提到的主機、HTTP 狀態與憑證訊息，確認該請求是否走預期代理。不要把存取權杖或完整代理網址貼到公開紀錄；分享錯誤訊息前，先遮蔽使用者名稱、權杖、內部網域和本機路徑。

Docker Hub：分清 CLI、daemon 與映像來源

執行 docker pull 的命令列工具會向 Docker daemon 提出請求，實際下載映像檔的通常是 daemon。因此，在終端機設定 HTTP_PROXY 或 HTTPS_PROXY，不代表 Docker daemon 一定會讀取相同變數。Docker Desktop、Linux 上的 Docker Engine，以及 CI 執行環境的設定入口可能不同，應依正在使用的平台文件，確認代理設定是套用在 daemon、建置容器，還是隻有目前的 shell。

變更 daemon 的代理設定後，通常需要依平台要求重新載入設定或重新啟動服務，再重新測試。操作前先保存原有設定，並確認本機代理是否允許 Docker daemon 所在環境存取。若代理只監聽使用者工作階段的本機介面，背景服務可能無法連到該位址；此時應先釐清服務執行者、網路命名空間與代理監聽範圍，不要盲目改成對所有網路介面開放。

若 Docker Hub 登入成功，但拉取映像時卡住，查看輸出是停在取得 manifest、下載 layer、驗證憑證還是重試請求。不同階段可能對應不同問題：DNS 或連線重設、映像名稱或標籤錯誤、帳號權限，以及服務端的使用限制，都可能導致失敗。代理只能改變請求的網路路徑，不能替代有效的 Docker Hub 登入，也不能解除服務端對帳號或請求的限制。

需要在建置容器內使用代理時，還要分別檢查 Docker build 的建置參數與容器執行環境。不要把含有帳密的代理 URL 寫進 Dockerfile、映像層、版本控制檔案或建置紀錄；這類資料可能隨映像或日誌被其他人取得。團隊環境應使用平台提供的祕密管理機制，並遵循組織對映像來源、憑證與網路存取的規範。

動手操作：按層驗證代理是否生效

以下流程適合用來判斷代理設定應放在哪一層。先選一個允許存取的測試目標，並記下目前用戶端模式、代理位址和工具版本。若設備上同時啟用了多個代理或 VPN 用戶端，先確認哪些程式會修改系統代理、路由或 DNS；不要在不清楚影響範圍時同時啟用多套網路接管功能。

1. 確認本機代理狀態：在用戶端檢查所選線路與本機監聽設定，確認代理仍在執行。不要假設訂閱匯入後所有系統流量都已自動轉送。
2. 檢查命令列環境：查看目前終端機是否設有代理環境變數，並確認代理位址和協定格式正確。使用臨時設定測試後，檢查關閉終端機或清除變數時，是否恢復原狀。
3. 單獨測試 Git：確認遠端網址的協定，再執行一次讀取型操作，例如檢查遠端或取得最新提交。若瀏覽器可用而 Git 不行，回頭檢查 Git 自身設定、SSH 與 HTTPS 的差異，以及憑證錯誤。
4. 單獨測試 Docker：確認 Docker daemon 已套用設定後，再拉取一個團隊允許使用的映像。觀察錯誤發生在連線、認證還是 layer 下載階段，不要只看命令是否開始執行。
5. 最後測試套件管理器：以目前專案指定的 registry 或套件來源進行安裝，確認設定來源、憑證和鎖定檔沒有被意外改動。
6. 還原並記錄：移除臨時代理設定，確認其他網站、內網及工作工具仍符合預期。記錄有效設定的範圍與還原方式，方便日後在相同設備重現。

測試過程中若只在某一步失敗，先不要擴大修改範圍。例如 Git 使用代理後正常、Docker 仍無法拉取，較合理的下一步是檢查 daemon 的代理，而不是再次變更 Git 設定。反之，如果多個工具都在同一網路環境中無法建立連線，則可檢查 DNS、系統路由、防火牆與代理用戶端狀態。

npm、pip 與套件來源：穩定不等於任意換源

npm 與 pip 各自有 registry、索引和設定檔，瀏覽器代理設定不一定能控制它們。遇到安裝逾時，先查看錯誤指出的套件來源與請求階段，再檢查目前生效的設定、環境變數和專案層級設定。團隊專案若有既定 registry、私有套件源、憑證或鎖定檔，應優先遵守專案文件；直接換成來路不明的鏡像，可能遇到套件不同步、完整性驗證不符或供應鏈風險。

更換套件來源也會影響後續維護。即使某個來源暫時較順，也應先確認它是否由組織批准、是否保留套件完整性檢查，以及是否能提供團隊需要的套件版本。不要為了排除網路問題而永久關閉 TLS 憑證驗證，或使用忽略錯誤的安裝選項；這些做法會降低下載內容的可信度，不能視為安全的加速設定。

如果只有特定套件下載失敗，查看套件名稱、版本、平台相依性與錯誤訊息，確認它是否需要編譯原始碼或另外下載二進位檔。安裝耗時不一定代表資料傳輸慢；編譯工具缺失、相依性衝突或快取損壞，也可能讓流程停在下載之後。先在乾淨環境重現，再依錯誤訊息檢查套件與本機建置條件，通常比反覆清除所有快取更有判斷力。

CI 與團隊環境：把設定和憑證分開管理

本機可用的代理，在 CI runner 上不一定可用。Runner 可能位於不同網路、使用容器或虛擬機，也可能由平台代管；設定應依 CI 平台與組織政策放在適當的工作階段或建置服務層。先確認工作流程在哪個執行環境下載程式碼、安裝套件與拉取映像，再決定代理環境變數或 daemon 設定的作用範圍。只在某個步驟匯出變數，不代表其他容器或服務也會繼承該設定。

CI 建置可以善用平台支援的依賴快取與映像快取，但快取鍵應能反映鎖定檔、建置環境或映像版本的變更。快取能減少重複下載，不能取代來源驗證或確保資料永遠最新；快取失效時，工作流程仍應能從可信任來源重新建立。若失敗只出現在冷啟動或快取更新時，請把快取命中與網路下載分開觀察，不要將兩者混為一談。

團隊共用設定時，不要把含有代理帳密、訂閱連結、存取權杖或私有套件憑證的設定檔提交到版本控制。使用 CI 平台的祕密變數或組織覈准的憑證管理方式，並限制可讀取的工作流程與人員。公開建置日誌、除錯輸出和螢幕截圖前，應檢查是否意外列出環境變數、代理網址、內部主機名稱或存取權杖；若憑證已外流，依組織程序撤銷或更新，而不是隻刪除日誌。

最後，確認使用代理、套件來源、Docker Hub 帳號與 CI runner 的方式符合服務條款及團隊政策。企業設備可能有指定的出口、防毒或零信任工具，個人新增的代理設定不應繞過組織的安全要求。若調整後無法解釋某個請求如何離開設備，先回復原設定並向管理者確認，再繼續測試。

• ✅ 為本機、Docker daemon、建置容器與 CI runner 分別記錄代理設定範圍。
• ✅ 使用團隊批准的套件來源，保留 TLS 憑證與套件完整性檢查。
• ✅ 透過祕密管理機制提供必要憑證，避免寫入程式碼、映像或公開日誌。
• ❌ 不要把「下載更快」當成忽略帳號限制、服務規範或公司政策的理由。