開發者 VPN 完整方⁠案：GitHub、Docker 與 npm 加⁠速設定

先分清楚 VPN 接管與工具代理

開發工具的連線方式通常比瀏覽器複雜。VPN 用戶端可能透過系統代理、TUN 虛擬網路介面卡，或兩者結合來接管流量；Git、Docker 和 npm 則可能讀取環境變數、各自的設定檔，甚至由獨立背景服務建立連線。瀏覽器可以開啟 GitHub，並不代表終端機中的 Git 一定能正常 clone。

系統代理適合遵循作業系統設定的應用程式，但命令列工具是否採用它，取決於工具本身與啟動環境。TUN 模式會處理更廣泛的 IP 流量，對不支援 HTTP 或 SOCKS 代理的程式較方便；不過它可能與 Docker Desktop、虛擬機器、企業安全軟體或其他 VPN 的虛擬介面卡互相影響。設定前應先確認目前只有一個工具負責預設路由，避免多個程式同時改寫網路路徑。

先固定一種代理表示方式

常見的代理表示方式包括 HTTP、HTTPS 與 SOCKS5。實際可用的位址與連接埠應以用戶端顯示內容為準，本文不提供虛構端點。若用戶端輸出的是本機代理，通常會以類似 127.0.0.1:連接埠 的形式呈現；若使用 TUN 模式，則不一定需要把每個工具逐一指向本機代理。

不要把含有帳號、密碼或訂閱資訊的完整代理網址直接提交到程式碼儲存庫。設定檔可以使用環境變數或本機未追蹤檔案，並在分享錯誤記錄前移除憑證、訂閱網址與私有網域。

GitHub 與 Git：從 clone 到推送逐項檢查

Git 可能同時涉及 HTTPS、SSH、憑證管理、遠端主機名稱解析與長時間傳輸。使用 HTTPS clone 時，可以先讓 Git 讀取環境變數，再視需要設定 Git 自身的代理；使用 SSH 時，則要另外處理 SSH 的 ProxyCommand 或網路接管方式。兩種方式不要混為一談。

HTTPS 遠端的設定方法

若 VPN 用戶端提供本機 HTTP 代理，可以在目前終端機工作階段設定環境變數。以下只是格式範例，PROXY_HOST 與 PROXY_PORT 必須替換成用戶端實際提供的值：

export HTTPS_PROXY=http://PROXY_HOST:PROXY_PORT
export HTTP_PROXY=http://PROXY_HOST:PROXY_PORT
git clone https://example.invalid/owner/project.git

Windows PowerShell 可使用相應的環境變數語法；若只希望 Git 使用代理，也可以設定 Git 的全域選項：

git config --global http.proxy http://PROXY_HOST:PROXY_PORT
git config --global https.proxy http://PROXY_HOST:PROXY_PORT
git config --global --get-regexp 'http\.(proxy|httpsproxy)'

完成測試後，應確認設定是否會影響公司內部 Git 服務或本地網域。若代理只應用於特定主機，可以使用更精確的 Git 設定，而不是把所有 HTTP 連線永久導向同一條路徑。當你改用 TUN 模式後，也要檢查是否仍保留過期的 Git 代理；兩層代理疊加可能造成連線失敗或認證錯誤。

SSH 遠端不要照搬 HTTPS 設定

SSH 不會自動採用 Git 的 http.proxy。若公司或網路環境允許使用 SSH，應依 SSH 用戶端支援的方式設定跳板或 ProxyCommand，並確認服務端政策與金鑰使用規範。若只是需要穩定取得公開程式碼，HTTPS 通常比較容易診斷；若需要推送私有專案，則應優先採用組織覈准的憑證與金鑰管理方式。

• ✅ 先確認目前遠端網址是 HTTPS 還是 SSH，再選擇對應的代理設定。
• ✅ 用 git config --list --show-origin 檢查設定到底來自哪個檔案。
• ✅ 切換線路後，結束原有 clone 或 fetch 工作，再重新建立連線。
• ❌ 不要把代理帳密、存取權杖或訂閱連結寫進公開的 Git 設定檔。

Docker 映像檔下載：設定客戶端還是 daemon

Docker 的特殊之處在於，執行 docker pull 的終端機只是控制客戶端，真正下載映像檔的可能是 Docker daemon。Docker Desktop、Linux 原生 Docker Engine、遠端 Docker 主機與 CI runner 的設定位置並不相同。因此，在終端機設定 HTTPS_PROXY，不一定能改變 daemon 的下載路徑。

先找出實際執行 Docker 的主機

本機使用 Docker Desktop 時，daemon 通常由 Desktop 管理；Linux 主機則可能由 systemd 啟動 Docker Engine；若環境變數中的 DOCKER_HOST 指向遠端主機，下載行為便會發生在遠端。先確認 Docker context、daemon 所在位置與目前使用的帳戶，再決定要修改 Desktop 設定、systemd drop-in，還是 CI 執行器的服務環境。

Docker 代理設定通常分為 daemon 代理與容器執行時代理。daemon 代理影響拉取映像檔、推送映像檔及與 Registry 的連線；容器內的程式是否需要代理，則應透過明確的建置參數或執行環境傳入。不要因為主機能拉取映像檔，就假設容器內的套件管理器也會自動使用相同代理。

Registry mirror 與 VPN 不是同一種方案

Registry mirror 是把映像檔請求導向另一個快取或鏡像服務；VPN 則是改變連線經過的網路路徑。某些環境適合使用組織覈准的內部 Registry，某些環境則只需要讓 Docker daemon 經由穩定線路連線。鏡像服務的可用性、內容同步與存取權限必須由管理者確認，不能把任意公開鏡像網址直接加入生產環境。

另外，Docker 映像檔可能包含多個 layer。下載速度忽快忽慢，可能與某一層沒有快取、Registry 回應、磁碟寫入或本機儲存空間有關。排查時應觀察 Docker 的輸出、磁碟使用量與 daemon 記錄，不要只根據單次下載時間判定線路品質。

npm 套件安裝：Registry、代理與憑證分開處理

npm 逾時可能來自 Registry 路徑、DNS、代理格式、TLS 憑證或 lockfile 中引用的其他套件來源。先確認目前 npm 使用哪個 Registry，再檢查代理設定，比直接增加逾時秒數更有效。若專案使用私有套件，還要區分公開套件的 Registry 與組織內部 scope 的 Registry。

查看目前 npm 設定

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

如果 VPN 用戶端提供本機 HTTP 代理，可以在 npm 設定中指定代理，但必須使用實際端點，並留意設定是否被寫入使用者層級的 .npmrc。若代理不再使用，應清除舊值，避免之後切換到其他網路時仍嘗試連線到已不存在的本機連接埠。

npm config set proxy http://PROXY_HOST:PROXY_PORT
npm config set https-proxy http://PROXY_HOST:PROXY_PORT
npm config get https-proxy

不要為了繞過連線問題而長期關閉 TLS 憑證驗證。像 strict-ssl=false 這類設定會降低連線驗證能力，應先檢查系統時間、企業憑證、代理的 TLS 終止方式與正確的 CA 設定。若專案有固定的 lockfile，也要檢查其中是否保存了已失效的自訂 Registry 或 tarball 位址。

避免把權杖放進專案檔案

npm 私有 Registry 常用存取權杖驗證。權杖應透過使用者層級設定、CI secret 或短期環境變數注入，不要把真實權杖寫入專案根目錄的公開 .npmrc。提交前可檢查 Git diff、CI 記錄與套件安裝輸出，確認沒有意外印出認證資訊。

CI 環境的穩定做法：可重現、可撤銷、少暴露

本機設定能運作，不代表 CI runner 也能運作。CI 可能使用容器、短期虛擬機器或受管理的自建執行器，網路出口、DNS 與 Docker daemon 都可能與開發者電腦不同。若組織已提供固定的建置網路或內部 Registry，應優先依照平台文件配置，不要自行在工作流程中下載未知的代理程式。

若 CI 需要代理，建議將代理位址、帳密與 Registry 權杖放在平台的加密 secrets 中，再透過工作階段環境變數傳入。環境變數名稱可依工具支援情況使用 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 等欄位；NO_PROXY 應加入內部 Git、Registry、服務名稱與本機位址，避免內部流量不必要地經過外部線路。

建置腳本應把網路設定與套件安裝分開記錄。先輸出不含祕密的診斷資訊，例如目前 Registry 名稱、Docker context 或代理是否已設定，再執行 clone、pull、install。不要用完整環境變數 dump 取代診斷，因為那可能把權杖與連線資訊寫入 CI 日誌。

1. 確認 runner 的網路政策、DNS 與出口是否允許存取目標服務。
2. 確認 Git、npm 與 Docker 分別由哪個程序建立連線。
3. 透過 secrets 注入必要設定，並為內部網域設定 NO_PROXY。
4. 使用固定 lockfile、覈准的 Registry 與可追蹤的映像檔來源。
5. 在工作完成後檢查日誌，確保沒有輸出代理密碼或存取權杖。

遇到逾時與下載失敗時的排錯順序

開發網路問題最好按照由底層到工具層的順序排查。先確認 VPN 用戶端目前是否已連線、規則是否把目標網域送往預期路徑，再檢查 DNS 解析與本機防火牆。接著分別測試 Git、Docker 和 npm，避免三個工具同時改設定而失去比較基準。

• ✅ 先記錄目前使用的接管方式、線路與工具版本，方便重現問題。
• ✅ 檢查 Git 的獨立代理、npm 的 Registry，以及 Docker daemon 的代理位置。
• ✅ 切換線路後重新建立 Git、Registry 與 SSH 連線，不沿用已中斷的長連線。
• ✅ 對內部服務使用 NO_PROXY 或組織指定路徑，避免破壞內網存取。
• ❌ 不要同時啟用兩個會修改預設路由的 VPN 或 TUN 工具。
• ❌ 不要以關閉 TLS 驗證、公開權杖或使用未知鏡像服務來換取短期成功。

如果只有某一個工具失敗，優先檢查它自己的設定與背景程序；如果所有工具都失敗，再回到 VPN 接管、DNS、路由與本機防火牆。若問題只發生在 CI，則應比較 runner 與本機的 DNS、出口、Registry 權限和憑證，不要直接把本機設定檔完整複製到建置環境。

對需要多平台工作的團隊而言，使用同一服務的 Windows、macOS、iOS、Android 或 Linux 官方用戶端，可以先完成基本連線，再依開發工具需求選擇相容的第三方客戶端。Clash Verge、sing-box、Shadowrocket 等客戶端對訂閱格式、協定核心與 TUN 能力的支援各有差異，匯入前應確認目標格式與用戶端版本。無論採用哪種客戶端，都應保留最小必要權限，並定期檢查訂閱連結是否曾出現在日誌或分享內容中。