GitHub 專案載入緩慢、Docker 映像檔一直停在下載中，或 npm、pip 安裝依賴時反覆逾時，這些問題不一定出在同一個環節。瀏覽器能開啟網站，不代表 Git、容器引擎和套件管理工具已使用相同的網路設定；不同資源也可能由不同網域或服務提供。
排查時先確認失敗發生在哪個工具、哪個目標，以及錯誤訊息屬於連線逾時、名稱解析、TLS 憑證還是權限問題。本文依照 GitHub、Docker、套件管理工具與 CI 的工作流程整理設定方向，並說明如何逐步驗證，避免在問題尚未定位前就盲目更換代理或鏡像來源。
先定位故障：不要把所有下載問題當成同一件事
開發工具的網路路徑通常不只一條。瀏覽器可能使用系統代理，Git 則讀取自己的代理設定；Docker CLI 會把請求交給 Docker daemon，映像檔下載由 daemon 或其建置元件處理；npm、pip 又各自有設定檔、環境變數與來源站點。因此，桌面端顯示已連線，只能說明某個連線路徑可用，不能證明每個命令列程式都會經過同一條路徑。
先保留完整錯誤訊息，並記錄執行命令、使用的工具版本、網路環境及失敗時間。若錯誤是 DNS 查詢失敗，應先檢查名稱解析；若是連線逾時或重設，再確認代理、路由與目標服務是否可達；若訊息指向憑證、認證或權限，則需分別檢查 TLS 憑證、登入狀態與存取權限。只看到「下載失敗」就更換套件源，可能掩蓋真正問題，甚至引入不可信的供應來源。
- ✅ 先確認失敗工具與失敗目標，不以瀏覽器測試代替命令列驗證。
- ✅ 分辨 DNS、逾時、TLS、認證與權限錯誤，再選擇對應排查方式。
- ❌ 不要為了排除憑證錯誤而關閉 TLS 驗證，也不要將存取權杖貼到公開日誌。
GitHub 專案：分開檢查 Git、網頁與大型檔案
GitHub 網頁、Git over HTTPS、SSH、發布頁的附件，以及 Git LFS 檔案，可能走不同的連線流程。網頁能正常載入，不等於命令列的 clone、fetch 或 push 一定成功；反過來說，Git 操作失敗也不代表整個 GitHub 網站都無法連線。先看錯誤發生在建立連線、驗證帳號、取得物件，還是下載外部附件，再決定要檢查哪一層。
若使用 HTTPS，Git 可透過自身的代理設定或執行環境中的代理變數連線。設定時先確認代理位址、連接埠及認證方式，並留意系統代理與 Git 設定可能互不相同。公司網路若提供受管理的代理，應依管理者指引配置；不要把含帳號密碼的代理字串寫入共用的全域設定或公開腳本。除錯完成後，也應檢查設定是否留下不再需要的憑證。
使用 SSH 時，HTTPS 代理設定不會自動套用到 SSH 連線。應確認 SSH 金鑰是否載入、遠端網址使用 HTTPS 還是 SSH，並依網路環境配置受支援的跳板或代理方式。遇到主機金鑰提示時，不要只為了讓命令繼續執行就跳過核對；應依可信任的來源確認主機身分。若只有 Git LFS 或發布附件失敗，查看工具輸出的實際下載目標，因為這些資源未必與 Git 物件使用相同的主機。
若採用代理工具的規則模式，請查看 Git 程式實際比對到的規則，而不是隻確認圖形介面顯示已啟動。選擇出口時，優先以目標服務能否穩定完成 clone、fetch 與套件下載作為依據；例如使用 JiuVPN 時，也應在自己的開發環境逐項驗證工具路徑，而不要把服務連線狀態直接當成 GitHub 可用性的保證。
Docker 映像檔：CLI、daemon 與建置環境各自檢查
執行 docker pull 時，命令列工具會與 Docker daemon 協作，真正取得映像檔的網路設定不一定等同於目前終端機的設定。若終端機能連線而 pull 仍逾時，應檢查 daemon 所在環境的代理設定；Docker Desktop 與 Linux 主機的配置入口不同，不能假設在 Shell 設定 HTTP_PROXY 後，daemon 就會自動讀取。
如果考慮使用 registry mirror，先確認它服務的登錄庫範圍、映像名稱規則、認證方式與信任狀態。Docker 的鏡像設定不會自動涵蓋所有第三方 registry，也不代表所有映像都能由該來源取得。不要把來源不明的鏡像加入正式環境；對重要映像，應檢查映像名稱、標籤或摘要，並遵守團隊的映像來源與簽章驗證政策。
多階段建置或 BuildKit 建置還可能涉及建置器自身的網路設定。主機可以 pull 基礎映像，不等於建置步驟中的套件安裝也會成功；反之，主機終端機中的代理變數也未必會傳入建置容器。需要代理時，使用該建置環境正式支援的傳遞方式，避免把代理密碼寫進 Dockerfile、映像層或建置日誌。檢查快取時，也要區分是快取命中、遠端下載，還是建置步驟本身失敗。
若問題只出現在 CI，請確認 runner、daemon、建置器及容器內命令各自的網路環境。自架 runner 可能使用主機服務設定，託管 runner 則受平台的網路政策與工作階段限制；兩者不能套用完全相同的操作假設。
動手排查：從最小測試逐步恢復完整流程
以下流程適合本機開發環境與測試 runner。每次只調整一個變數，並使用可安全重複的測試專案或映像；不要用正式部署中的敏感程式碼或憑證作為網路測試資料。
- 記錄原始狀態。保存錯誤訊息、命令、工具版本、作業系統及當下的代理模式。若近期修改過 DNS、代理或防火牆設定，也一併記下，方便必要時還原。
- 確認基本解析與連線。以作業系統提供的診斷工具檢查目標主機名稱是否能解析，並觀察連線是在解析前後哪個階段失敗。不要只用 ping 判斷 HTTPS 服務是否可用，因為目標可能不回應 ICMP，但仍能接受應用程式連線。
- 單獨測試 Git。使用非敏感的測試儲存庫執行 clone 或 fetch，確認遠端網址、協定與代理設定一致。若使用 SSH，再單獨檢查金鑰和 SSH 設定；若使用 HTTPS，確認 Git 是否讀取預期的代理配置。
- 單獨測試容器映像。從團隊覈准的來源拉取已知可用的測試映像，分辨問題在 registry 連線、認證、鏡像配置或 daemon 代理。若 pull 成功但 build 失敗，轉而檢查建置器及建置步驟的網路。
- 測試套件管理工具。分別確認 npm 或 pip 使用的 registry、設定檔與憑證。若更換索引來源，先核對它是否為團隊或專案信任的來源，並注意套件名稱混淆、私有套件範圍及鎖定檔設定。
- 一次只改一項設定。切換代理、修正 DNS 或調整鏡像後，重跑同一個測試命令並比較結果。完成後清理臨時環境變數、除錯輸出及不再使用的憑證。
記錄測試條件能避免把偶然恢復誤認成設定有效。若更換網路出口後症狀消失，仍應再確認是路由、DNS、服務端限制還是原代理配置造成差異。這類比較應使用同一台裝置、同一工具和同一目標，並遵守公司網路與專案的安全規範。
先定位哪個程式在連線，再對該程式設定代理、來源或憑證；Git、Docker daemon、建置器與套件管理工具各自驗證，通常比一次更換整套網路設定更容易找到根因。
npm、pip、CI 與 API：把來源與憑證納入設定
npm 與 pip 都可能從設定的索引或 registry 取得套件，但專案、使用者與全域設定的優先順序，以及私有套件的認證方法，會因工具設定而異。更換公開套件來源前，先確認專案是否指定了私有 registry、套件範圍或內部索引；設定不一致時，可能造成某些依賴可下載、另一些卻找不到。若遇到憑證錯誤，應檢查系統時間、憑證鏈及企業代理的受信任憑證配置，不要使用停用 TLS 驗證的方式掩蓋問題。
CI 工作流程要把代理與憑證分成不同範圍管理。runner 主機能連線，不代表工作容器、服務容器及建置程序都能連線；工作流程中的遮罩也不代表祕密在所有除錯輸出中都安全。使用平台提供的祕密管理機制，限制憑證可用的工作與權限，避免將 token、代理密碼或私有索引憑證硬編碼進設定檔、建置參數及快取。
使用 GitHub API 時，請區分連線問題與 API 的認證、權限或速率限制回應。依官方文件選擇適當的認證方式與最小必要權限，安全保存 token，並在程式中妥善處理錯誤回應與重試。連線代理只能影響請求經過的路徑，不會增加 API 權限，也不能取代對配額與服務政策的遵循。
在桌面端，可用 Clash Verge 等相容用戶端依工作需求設定規則或代理模式；但 Git、Docker daemon 及 CI runner 是否套用其系統代理，仍要分別驗證。第三方客戶端的設定名稱、支援協定與行為可能不同，請以當前版本文件及實際測試為準。無論採用哪種方式，都不要將完整訂閱連結或含認證資訊的設定檔貼到公開 issue、日誌或線上檢查工具。
- ✅ 套件來源以專案與團隊覈准設定為準，變更前檢查私有套件與鎖定檔。
- ✅ CI 憑證使用祕密管理並限制權限，並檢查 runner、容器與建置程序的網路差異。
- ❌ 不要把 API token、代理密碼或完整訂閱連結寫入 Dockerfile、公開工作流程或除錯輸出。
最後，將驗證結果寫成可重現的團隊排查紀錄：記下出問題的工具、設定層與錯誤類型，不記錄祕密值。如此一來，遇到 GitHub、Docker 或套件下載故障時，就能先縮小範圍，再按需要檢查代理、來源、DNS、TLS 或權限，而不必以犧牲供應鏈安全換取暫時可用。