開發者 GitHub、Docker、npm 網路加⁠速：本機開發與 CI 設定懶人包

GitHub 專案下載慢、Docker 映像檔拉取失敗，或 npm 安裝卡在解析依賴，表面上都是「網路不順」，實際原因卻可能不同：Git 使用的傳輸方式、Docker daemon 的代理設定、套件登錄站、DNS 解析及 TLS 憑證都各有自己的設定範圍。有效的處理方式不是把所有流量都指向同一個代理，而是先確認是哪個程式、哪個網路請求遇到問題，再設定對應的代理與信任鏈。

以下整理本機開發與 CI 建置常見的檢查順序。各工具的設定會依作業系統、版本及團隊網路政策而異；請先核對官方文件與內部規範，並避免把憑證、帳密或代理授權資訊寫進專案檔案。

先定位問題：不要把所有錯誤都當成代理故障

開始修改設定前，先記錄失敗的命令、完整錯誤訊息、目標主機名稱及發生時間。若只有 GitHub 網頁打不開，不代表 Git over SSH、HTTPS API 或容器登錄站也有相同問題；反過來說，瀏覽器能開啟網站，也不代表命令列程式已使用相同代理。不同應用程式可能各自讀取系統代理、環境變數、工具專用設定，或完全不讀取代理。

可先依症狀縮小範圍：名稱無法解析時檢查 DNS；連線逾時時確認路由、防火牆與代理可達性；TLS 驗證錯誤時檢查系統時間、信任的憑證鏈及攔截式代理政策；只有特定映像檔或套件失敗時，再檢查登錄站、版本標籤、權限與速率限制。不要用停用 TLS 驗證的方式「測試看看」，這會掩蓋根本原因，也會降低供應鏈安全性。

• ✅ 比較同一目標在瀏覽器、命令列與 CI 中的結果，確認問題是否只出現在單一工具。
• ✅ 先看錯誤發生在 DNS、建立連線、TLS 握手，還是下載回應階段。
• ✅ 記下目前的代理環境變數與工具設定，修改前保留可還原的狀態。
• ❌ 不要為了排錯而關閉憑證驗證，或將存取權杖貼進公開日誌。

若開發環境需要跨平台維持一致，應把代理位址、憑證安裝方式與例外網域納入團隊文件。在規劃連線工具與工作流程時，也可參考 VPNText 的平台資訊；實際設定仍應遵守所在地網路規範及組織安全政策。

GitHub 與 npm：分別設定傳輸方式和套件來源

Git 透過 HTTPS 連線時，通常會使用 Git 本身、Git 所呼叫的憑證管理工具，或目前執行環境提供的代理設定。可以先確認遠端網址使用 HTTPS 還是 SSH，再依團隊規範設定。若 HTTPS 代理確實需要透過 Git 設定，可用下列方式指定；其中位址應替換成組織覈准的代理服務，並避免將含有帳密的完整網址提交到共用設定檔。

git config --global http.proxy http://proxy.example:8080
git config --global https.proxy http://proxy.example:8080
git config --global --get-regexp 'http.*proxy'

若代理只應套用在部分工作環境，可改用環境變數或只設定單一儲存庫，並在工作結束後檢查是否留下過度寬泛的全域設定。HTTPS 代理與 SSH 連線不是同一套設定：SSH 使用自己的主機、連接埠、金鑰與網路路徑；設定 Git 的 HTTPS 代理，不會自動替 SSH 通道建立代理。遇到 SSH 逾時，請檢查 SSH 設定及組織覈准的連線方式，不要直接把 HTTPS 代理參數複製過去。

npm 的套件來源則應透過專案或使用者層級的設定管理。團隊若提供私有登錄站，應確認套件範圍對應正確，並使用安全的憑證儲存方式。不要因為下載較慢，就隨意將套件來源改成來路不明的鏡像；同名套件可能帶來供應鏈風險。可以先檢查目前使用的登錄站與代理設定：

npm config get registry
npm config get proxy
npm config get https-proxy

代理環境變數常見名稱包括 HTTP_PROXY、HTTPS_PROXY 與 NO_PROXY，但程式是否讀取、大小寫優先順序及例外網域格式，可能依工具與執行環境而異。設定 NO_PROXY 時，應明確列出確實需要直連的內部主機或網域，並確認逗號分隔格式符合使用中的工具。若內部登錄站被錯誤排除在代理之外，便可能出現本機可用、CI 取不到套件的差異。

Docker 映像檔與建置：分清 daemon、用戶端和建置程序

Docker 拉取映像檔時，網路請求通常由 Docker daemon 或容器執行環境處理，不一定沿用終端機中的代理變數。因此，命令列已設定 HTTPS_PROXY，不能據此認定 daemon 也能連到登錄站。Docker Desktop、Linux 上的 Docker Engine，以及由 CI 平台管理的建置器，設定入口並不相同；請依實際執行 daemon 的環境查閱對應文件。

建置映像檔時還有另一層：Dockerfile 裡執行的套件安裝命令，可能需要建置階段的代理設定。即使 daemon 可以下載基底映像，建置容器內的 apt、npm 或其他工具仍可能連線失敗。相反地，建置階段能安裝套件，也不代表 daemon 能拉取新的基底映像。應分別測試「拉取映像」與「執行建置」兩個環節，並檢查建置日誌中實際失敗的步驟。

請勿把代理密碼、套件登錄權杖或其他祕密寫成 Dockerfile 的永久環境變數、建置參數或映像層內容。建置參數可能留在映像中繼資料、快取或記錄裡，不適合作為祕密傳遞機制。若建置工作確實需要授權資訊，使用建置工具支援的祕密掛載功能或 CI 的祕密管理機制，並依專案政策限制可讀取的範圍。

映像檔來源也要可追溯。使用清楚的登錄站與映像名稱，避免以不明來源的替代映像處理連線問題；團隊可透過覈准的內部快取或登錄站降低重複下載，但應同步管理映像更新、存取權限與掃描政策。映像標籤可能會移動，重要建置可依團隊規範固定版本或摘要，以便重現建置結果。

動手排查：由本機設定一路驗證到套件與映像

以下流程適合在有權限的開發環境中使用。每次只改一層設定，完成後立刻測試，能避免多個變更互相遮掩。若是公司管理的代理或憑證，先向管理者確認覈准的主機名稱、憑證安裝方式及例外網域，不要自行下載陌生憑證並設為受信任。

1. 確認目標主機與工具。從錯誤訊息找出連不上的是 GitHub、套件登錄站、映像登錄站，還是內部 API。確認失敗命令是在本機終端機、容器內或 CI runner 執行。
2. 檢查名稱解析。使用作業系統提供的 DNS 查詢工具確認目標主機是否能解析，並比較不同網路環境的結果。若只有內部網域解析異常，確認是否需要組織指定的 DNS 或分流規則；不要把固定 IP 長期寫進設定取代 DNS。
3. 檢查代理是否被工具讀取。查看目前 shell 的 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 等環境變數，再檢查 Git 或 npm 的專用設定。遮蔽授權資訊後再分享輸出，避免把代理帳密貼入工單或終端機錄影。
4. 分開驗證 Git 與套件來源。先讀取 Git 遠端網址並測試必要的讀取操作，再查詢 npm 登錄站設定與套件中繼資料。若只有下載內容失敗，確認登錄站、存取權限及套件版本，而不是重複更改 DNS。
5. 分開驗證 Docker 拉取與建置。先測試取得基底映像，再執行會安裝套件的建置步驟。若前者成功、後者失敗，問題較可能在建置程序的代理、DNS、憑證或套件來源設定。
6. 清理測試設定。檢查 shell 設定檔、Git 全域設定、npm 設定及容器建置檔，移除臨時測試留下的代理或除錯選項。重新執行必要的基本操作，確認環境沒有依賴偶然存在的本機設定。

如果工具回報憑證簽發者不受信任，先確認系統時間與企業憑證政策，再檢查相關程式使用的是哪個信任存放區。Node.js、Git、作業系統與容器基底映像可能各自採用不同的 CA 憑證來源。不要以 NODE_TLS_REJECT_UNAUTHORIZED 等方式關閉驗證；正確做法是透過管理者覈准的管道安裝必要 CA，並在更新基底映像時維持憑證套件更新。

CI 建置與 API 測試：讓設定可重現、祕密不外洩

CI runner 的網路設定應由平台管理者或專案維護者明確配置，不要假設它會繼承開發者電腦上的代理、DNS 或憑證。若工作流程在本機成功、CI 失敗，逐項比較 runner 的執行環境、工具版本、環境變數、憑證存放區、登錄站權限及網路出口政策。將必須的設定放在受控的 runner 設定或工作流程祕密管理中，而非寫死在公開的建置檔。

CI 祕密應採最小權限，並限制可觸發建置的分支與工作流程。避免在除錯時輸出完整環境變數、帶有授權資訊的網址、套件設定檔或 HTTP 標頭；平台通常可遮蔽已登錄的祕密，但遮蔽機制不能取代安全設計。若權杖曾出現在提交紀錄或建置日誌，應依團隊程序撤銷並重新簽發，而不是隻刪除可見文字。

API 測試也要區分代理與應用程式錯誤。先確認 API 主機解析結果、連線路徑與 TLS 憑證，再檢查回應狀態、請求標頭及認證方式。若使用代理攔截 HTTPS，應只在獲準的測試環境中安裝管理者提供的 CA；不要為了讓測試通過而略過主機名稱或憑證驗證。測試日誌應遮蔽權杖、Cookie、個人資料與請求本文中的敏感欄位。

要讓 CI 與本機行為更一致，可把非祕密設定版本化，例如工具版本、套件鎖定檔、映像標籤政策與建置命令；祕密、代理密碼與私鑰則放入受控的執行環境。更新 Node.js、Docker 或套件管理工具後，安排一次乾淨建置，確認快取沒有掩蓋缺少的網路設定。當排查結果涉及網路出口或憑證變更時，記錄負責人、適用範圍與回復方式，方便團隊後續維護。