配置 約 10 分鐘

開發者 GitHub、Docker、npm 下⁠載卡關？網路設定一次整理

整理 GitHub 程式碼同步、Docker 映像檔下載和 npm 套件安裝的實用調校方式，涵蓋代理、Registry、DNS 與連線測試。從個人開發環境到 CI 建置流程，都能依需求逐步排查，並兼顧團隊設定與帳號憑證安全。

GitHub 程式碼同步、Docker 映像檔下載或 npm 套件安裝卡住時，不一定是同一種網路問題。Git 用戶端、Docker daemon、建置容器和 npm 程序可能各自使用不同的代理設定；DNS 解析、憑證檢查或 Registry 服務狀態，也都可能造成看似相同的逾時與連線失敗。排查時先確認哪個工具、哪個步驟失敗，再一次調整一項設定，最後用原本失敗的操作驗證結果。以下以正當開發、依服務條款存取為前提，整理適用於個人電腦與 CI 建置環境的檢查方式。

先畫出請求路徑：不要把所有問題都歸給代理

一個看似簡單的開發操作，可能經過多個不同的網路環節。執行 Git clone 時，請求由 Git 程序發出；Docker pull 通常由 Docker daemon 連線到 Registry，而非由終端機裡的 Docker 命令直接下載；Docker build 期間，建置容器還可能另外下載基底映像檔或執行套件安裝；npm install 則由 npm 程序連線至設定中的 Registry。即使瀏覽器可以開啟網站，也不能因此確認以上每個程序都能使用相同的代理。

先記錄錯誤發生的具體階段：是網域解析失敗、TCP 連線逾時、TLS 憑證錯誤、HTTP 權限拒絕，還是下載已開始但中途斷開。錯誤訊息中的網域名稱、連線階段與狀態碼通常比「速度很慢」更有診斷價值。檢查時不要把含有存取權杖、私有 Registry 登入資訊或代理密碼的完整命令與日誌直接貼到公開討論區。

  • ✅ 先判斷失敗發生在 Git、Docker daemon、建置容器，還是 npm。
  • ✅ 分清楚 DNS、代理連線、TLS 憑證與服務端回應等不同錯誤類型。
  • ✅ 保留錯誤文字與執行環境資訊，移除權杖、密碼及私有專案名稱後再分享。
  • ❌ 不要同時改 DNS、代理、Registry 與憑證設定，否則難以確認真正有效的調整。

GitHub 同步：先確認 Git 使用的協定與代理

GitHub 專案常見的遠端位址使用 HTTPS 或 SSH。HTTPS 傳輸通常會讀取 Git 自身的代理設定，也可能受目前 shell 的代理環境變數影響；SSH 則使用 SSH 用戶端的連線設定，單純新增 Git 的 HTTP 代理設定通常不會改變 SSH 流量。可以先執行 git remote -v 查看目前專案使用的遠端協定，再依實際方式排查。若同一專案的 clone 與 push 行為不同，也要確認遠端位址和帳號權限是否一致。

在已經有可信任代理服務，且其位址由管理者或服務提供方確認的情況下，可在 shell 設定代理環境變數，再用 git ls-remote 測試遠端是否能回傳參照資訊。以下使用佔位值示意，不要照抄成真實位址：

export HTTPS_PROXY="http://proxy.example"
export HTTP_PROXY="http://proxy.example"
git ls-remote https://github.com/OWNER/REPOSITORY.git

如果希望 Git 對 HTTPS 遠端使用代理，也可設定 Git 的 http.proxy；對所有專案設定前，先考慮是否會影響連到內部伺服器的流量。完成測試後，使用 git config --show-origin --get-regexp 'http\..*proxy' 檢查設定來源，並透過 git config --global --unset http.proxy 移除不再需要的全域值。若代理需要帳密，不要把憑證直接寫進共享的設定檔、專案檔案或 shell 歷程記錄。

SSH 遠端若無法連線，應另行檢查 SSH 金鑰、主機驗證與 SSH 用戶端設定；不能只因 HTTPS 代理可用，就推定 SSH 也會自動走代理。企業網路可能另有經覈准的 SSH 閘道或替代存取方式，應依管理者提供的設定處理，不要盲目關閉主機金鑰檢查。

判斷重點：先看遠端位址是 HTTPS 還是 SSH，再確認代理設定套用在哪個程序；Git 的 HTTP 代理設定不等於整台電腦的所有連線都會經過代理。

Docker 映像檔：分開檢查 daemon、Registry 與建置程序

docker pull 的網路請求通常由 Docker daemon 發出。若只在目前終端機設定 HTTP_PROXY 或 HTTPS_PROXY，daemon 未必會讀取這些變數；在桌面版 Docker、Linux 服務或 CI runner 上，代理設定入口也可能不同。先確認 Docker daemon 的執行方式及管理文件，再依該環境設定代理，套用修改後重新啟動相應服務，並以原本的映像檔拉取命令測試。不要為了排錯就把代理密碼放進可提交至版本控制的設定檔。

Docker Registry 設定與代理設定是兩件事。代理負責請求如何經過網路；Registry 決定要向哪個映像檔服務查詢。Docker 的 Registry mirror 功能有其適用範圍，設定前要確認所用服務確實支援該用途、內容來源可信，且符合組織的安全規範。不要隨意改用來源不明的鏡像站，也不要因為映像檔名稱相同，就假定其發布者與內容必然一致。對私有 Registry，還要分別確認登入憑證、命名空間、映像檔標籤和帳號存取權限。

若 docker pull 成功但 docker build 失敗，問題可能發生在建置階段。Dockerfile 中的套件安裝命令由建置程序或建置容器執行，其代理環境不一定與 daemon 相同。檢查建置工具支援的代理參數，並只將必要的代理設定傳入建置工作；不要把含密碼的代理 URL 固定寫進 Dockerfile，因為建置歷史或映像層可能保留敏感資訊。使用 BuildKit 等建置功能時，依官方文件採用適當的 secret 或代理傳遞方式，並避免將憑證納入映像檔。

現象 優先檢查 避免的誤判
docker pull 逾時 daemon 的代理、DNS、Registry 狀態與網路政策 只設定終端機變數便假設 daemon 已使用代理
pull 成功但 build 失敗 建置程序、Dockerfile 內的下載步驟與建置代理傳遞 把所有建置錯誤都當成映像檔下載問題
私有映像檔被拒絕 登入狀態、映像檔路徑、標籤與存取權限 反覆更換 DNS 或 Registry mirror 來處理權限錯誤

npm 套件安裝：確認 Registry、代理與憑證

先執行 npm config get registry 查看目前使用的 Registry，再檢查專案、使用者層級與全域的 npm 設定。官方 Registry 常見位址為 https://registry.npmjs.org/；若專案使用企業私有 Registry，應保留團隊指定的設定，不要為了暫時排錯而直接覆寫共享專案的 .npmrc。可用 npm ping 測試 Registry 是否回應，再以原本的套件安裝命令確認實際下載流程。

npm 可以使用代理相關設定，但代理值應來自可信任的網路管理者或服務設定。若需要修改，可先檢查 npm config get proxy 與 npm config get https-proxy，並確認設定值是否來自專案檔案、個人設定或環境變數。代理需要驗證時，尤其要留意設定是否會以明文寫入使用者目錄、CI 輸出或診斷日誌。排錯結束後，移除臨時設定，並輪替意外暴露的憑證。

遇到 TLS 或憑證錯誤時，不要把 strict-ssl 關閉當成一般解法。這會削弱對 Registry 身分與連線安全性的驗證，可能掩蓋代理攔截、憑證鏈錯誤或企業根憑證未正確安裝等問題。應檢查系統時間、憑證鏈、組織覈准的根憑證與代理設定；若使用企業內部套件服務，依管理者提供的憑證部署方式設定。只有在確認憑證來源與安裝範圍後，才進行相應修正。

安裝卡住也可能與 lockfile、快取或套件版本解析有關，而非網路本身。先閱讀 npm 的錯誤摘要，避免一開始就刪除 lockfile 或清空快取，否則可能改變解析結果，讓團隊環境與本機產生差異。若 Registry 可連線但某個套件仍失敗，確認套件名稱、版本、私有套件權限及 lockfile 中記錄的來源，再判斷是否需要重新整理快取。

動手排查：從可重現的測試逐步定位

以下流程適合在自己的開發環境中操作。每完成一個步驟，就用同一個失敗目標重試並記錄結果；不要同時更換多個設定。CI 環境也可採用相同判斷順序，但應透過 CI 的 secret 管理機制提供敏感資料，不要把代理帳密或 Registry 權杖寫入建置日誌。

  1. 確認目標網域與操作階段。記下失敗的 Git 遠端、Docker Registry 或 npm Registry，以及錯誤出現於解析、連線、TLS、授權或下載階段。檢查官方服務狀態與組織網路政策，排除服務端暫時異常或帳號權限問題。
  2. 確認程序是否使用預期代理。分別檢查 shell 環境變數、Git 設定、Docker daemon 設定及 npm 設定。若瀏覽器能連線而 CLI 不能，優先確認 CLI 程序是否取得代理設定，而不是立刻更換 DNS。
  3. 測試名稱解析與 TLS。使用系統提供的 DNS 查詢工具確認目標網域可解析，再以相同環境測試 HTTPS 連線。若錯誤指向憑證，檢查系統時間、憑證鏈及覈准的企業憑證，不要略過 TLS 驗證來換取表面上的成功。
  4. 一次只調整一項。先修正明確錯誤的代理或 Registry 設定，再重新執行 git ls-remote、docker pull 或 npm ping。確認測試結果後，才進行下一項修改，並記下修改位置與回復方式。
  5. 在原工作流程中驗證。獨立測試成功後，再執行實際的 clone、映像檔拉取、建置或套件安裝。測試命令成功不代表完整工作流程一定成功，尤其 Docker build 內部的下載步驟與 npm 私有套件授權仍需分別確認。
  6. 清理臨時設定與憑證。移除不再需要的全域代理值，確認沒有將私密資訊寫進專案、容器映像或 CI 記錄。若憑證曾被公開或提交，應依服務提供方的方式撤銷或更新。

團隊與 CI：可重複設定，也要可安全回復

個人電腦能成功，不代表 CI runner 會有相同的 DNS、代理或信任憑證。CI 通常使用獨立的執行環境，Docker daemon 也可能由 runner 管理。應確認建置工作在哪個執行器中運行、哪一層負責拉取映像檔，以及套件安裝是在主機還是容器內進行。將設定放在正確的執行層級，比在工作流程裡反覆增加代理變數更容易維護。

團隊可在文件中說明需要的 Registry 位址、代理設定入口、憑證安裝方式與測試命令，但不要將個人憑證提交到版本控制。CI 的代理與套件登入資訊應以最小必要權限提供，並避免在錯誤訊息或除錯輸出中展開 secret。若使用內部 Registry mirror，記錄其維護責任與映像檔來源驗證方式；發生供應鏈或憑證疑慮時，團隊才有依據調查，而不是隻看下載速度。

網路設定調整完成後，保留一份不含敏感資料的變更紀錄：說明修改了哪一層設定、解決哪一類錯誤、如何驗證，以及如何回復。這能避免下一位開發者照著錯誤環境變數操作，也能讓 CI 問題更容易重現。若問題只在特定網路或單一執行器出現，應比較 DNS、代理出口、憑證信任與權限差異，不要把個人環境中的設定直接複製到所有工作站。

總結來說，GitHub、Docker 與 npm 的下載問題，第一步不是尋找一個「通用加速開關」，而是辨認實際發出請求的程序，再逐層檢查代理、Registry、DNS、TLS 與帳號權限。讓設定符合工具的執行位置、保留憑證驗證、避免公開敏感資訊，才能同時改善排查效率與團隊建置安全。

免費試用