開發者 VPN 完整配置：GitHub、Docker、npm 加速一次搞定

開發者 VPN 配置不能只處理瀏覽器開網頁的問題。GitHub 的程式碼同步、Docker Hub 的映像檔拉取、npm 與 pip 套件下載，以及 CI 建置中的依賴安裝，可能分別使用不同的程序、DNS 解析方式與網路代理設定。瀏覽器已經可以連線，不代表終端機、Docker daemon 或 CI runner 也會自動使用同一條通道。

這類問題最常見的原因，是代理只套用在圖形介面，沒有傳遞到命令列工具；或者系統代理已經啟用，但 Docker daemon 仍在另一個服務環境中執行。也有一些情況是 GitHub 可以開啟，Git over HTTPS 卻在憑證或代理握手階段失敗；npm 能查詢套件資訊，實際下載 tarball 時卻因 DNS、出口或分流規則不同而逾時。

本文會從網路層、用戶端層與工具層逐步整理配置方式，涵蓋 Windows、macOS、Linux，以及 Clash Verge、sing-box、Shadowrocket 等相容用戶端。重點不是把所有流量一律送入 VPN，而是讓需要穩定連線的開發工具使用可檢查的代理，同時保留本地服務、區域網路與內部網域的正常存取。

先看結論：開發者 VPN 應該比較什麼

開發用途的選擇標準，與單純瀏覽網頁不同。首先要確認服務能否在你的作業系統上正常使用，接著確認用戶端是否支援訂閱匯入、系統代理、TUN 或虛擬網路模式，最後才比較節點地區與線路類型。若只看節點名稱，很容易忽略終端機程序是否真的取得代理設定。

• ✅ 優先選擇能清楚顯示系統代理狀態、連線日誌與目前節點的用戶端。
• ✅ 將 Git、npm、pip 與 Docker 分開驗證，不要以瀏覽器結果代替全部結論。
• ✅ 需要完整接管未遵循系統代理的程序時，再評估 TUN 或虛擬網路模式。
• ❌ 不要同時開啟兩個代理用戶端，否則路由表、DNS 和本機連接埠可能互相衝突。
• ❌ 不要把訂閱連結貼到不受信任的轉換網站或公開問題回報中。

如果日常工作包含大量映像檔、套件或原始碼同步，月訂閱可按照每月用量選擇 ¥9.9/月含 60GB、¥18/月含 250GB 或 ¥28/月含 500GB。月訂閱流量按開通日每月重置；若是一次性建置、測試或短期專案，也可以比較 ¥158/300GB、¥358/1000GB、¥658/3000GB 的流量包，流量包用完為止且永久不過期。

用戶端、訂閱與協定要先分清楚

訂閱連結是設定的交付方式，不等於 VPN 用戶端，也不等於某一種協定。用戶端取得訂閱後，通常會解析出節點名稱、伺服器位址、連接埠、驗證資料與協定參數，再讓使用者選擇連線項目。訂閱更新成功，只代表設定可以被取得，並不代表每個節點都能連線，也不代表 Git、Docker 或 CI 已經使用代理。

Windows、macOS、iOS、Android 與 Linux 可以使用官方客戶端，依服務提供的訂閱連結一鍵匯入；也可以在相容情況下使用 Clash Verge、sing-box、Shadowrocket 等第三方客戶端。不同客戶端的規則語法、TUN 支援、DNS 接管、背景運作和權限要求並不完全相同，因此匯入相同訂閱後，實際行為可能有差異。

常見協定如何理解

Shadowsocks 通常被視為輕量的加密代理方式，適合搭配支援代理的應用程式或規則型客戶端。VMess 是 V2Ray 生態常見的通訊協定，實際效果仍取決於傳輸層、TLS、伺服器端配置與客戶端實作。Trojan 常利用 TLS 建立較接近一般加密連線的外觀，但是否穩定仍要看網路路徑與伺服器配置。Hysteria2 基於 UDP，設計上著重在高延遲、封包遺失或頻寬波動環境中的傳輸適應性，但如果目前網路限制 UDP，可能無法連線或退化。WireGuard 則是現代 VPN 協定，透過虛擬網路介面處理較完整的系統流量，對需要多個非瀏覽器工具一起工作的場景較容易理解。

協定名稱不能直接等同於速度或安全結論。TCP 型代理在某些受限網路中較容易建立連線，UDP 型協定則可能在封包遺失環境中有不同表現；但本地網路、入口品質、跨境路徑、出口網路與目標服務都會影響最終結果。測試時應一次只更換一個變數，否則同時切換協定、節點與代理模式，最後無法知道是哪個調整造成改善或惡化。

系統代理與 TUN 模式的差異

系統代理通常透過 HTTP、HTTPS 或 SOCKS 代理設定，讓遵循作業系統代理的瀏覽器與工具自動轉送請求。這種方式操作簡單，也容易保留本地網路的直連，但不是每個程式都會讀取系統代理。Docker daemon、某些 Java 程式、獨立更新器與自帶網路堆疊的工具，可能需要單獨設定。

TUN 模式會建立虛擬網路介面，讓更多沒有讀取系統代理的流量也能依照規則進入通道。它適合需要同時處理多種協定、容器工具與背景服務的環境，但也會增加 DNS、區域網路和本地服務排錯的複雜度。啟用前應先確認客戶端具備必要權限，並保留對本機網段、Docker bridge、公司內部網域的直連規則。

終端機代理：Git、npm 與 pip 分別設定

完成 VPN 連線後，先在用戶端查看本機 HTTP 或 SOCKS 代理的監聽位址與連接埠。以下範例使用佔位符，不代表固定值；實際值應以客戶端顯示內容為準。不要直接複製未確認的連接埠，也不要把包含密碼的代理網址寫入會提交到版本庫的設定檔。

# 只在目前終端機工作階段使用
export HTTP_PROXY="http://127.0.0.1:PORT"
export HTTPS_PROXY="http://127.0.0.1:PORT"
export ALL_PROXY="socks5://127.0.0.1:PORT"

# 檢查目前 shell 是否已載入
env | grep -i proxy

Windows PowerShell 可使用 $env:HTTP_PROXY、$env:HTTPS_PROXY 與 $env:ALL_PROXY 設定目前工作階段；若希望長期使用，應透過系統環境變數或專案工具的正式設定管理，而不是把敏感內容硬編碼在腳本中。完成測試後，可清除變數，確認工具在無代理狀態下的錯誤是否與預期一致。

Git 與 GitHub

Git over HTTPS 通常會讀取 Git 的代理設定，也可能受環境變數影響。可以先用單次命令測試，避免直接修改全域設定：

git -c http.proxy=http://127.0.0.1:PORT ls-remote https://github.com/ORG/REPO.git

如果單次設定有效，再決定是否寫入全域 Git 設定。檢查時要注意代理協定是否匹配：HTTP 代理與 SOCKS 代理的寫法不同，將 SOCKS 位址誤填成 HTTP，常見結果是連接埠可達但 TLS 或請求建立失敗。若使用 SSH 方式存取 GitHub，http.proxy 不會自動代理 SSH；此時需要在 SSH 設定中另行處理，或改用組織允許的 HTTPS 存取方式。

GitHub 登入與程式碼同步也可能受到主機金鑰、憑證、代理驗證和分流規則影響。不要為了繞過錯誤而關閉 TLS 憑證驗證。應先確認系統時間、根憑證、代理類型和目前出口，再查看 Git 的詳細錯誤輸出。

npm 與 pip

npm 具有自己的代理設定，也會受到部分環境變數影響。若只需要在目前專案測試，可以先使用命令列參數或專案層級設定；長期設定前，應確認團隊是否已有私有 registry，避免把公開套件來源不小心覆蓋。npm 的套件資訊與實際 tarball 下載可能經過不同網域，因此測試不能只執行查詢命令。

npm config set proxy http://127.0.0.1:PORT
npm config set https-proxy http://127.0.0.1:PORT
npm config get proxy
npm config get https-proxy

pip 通常可以使用 HTTP_PROXY、HTTPS_PROXY 或命令列代理參數。若套件安裝失敗，應區分索引服務無法連線、套件檔案下載逾時、TLS 憑證錯誤與本地編譯失敗。VPN 只能處理網路路徑，不能修復 Python 版本不相容、編譯器缺少或套件本身的依賴衝突。

python -m pip install --proxy http://127.0.0.1:PORT PACKAGE_NAME
python -m pip config list

在企業或團隊環境中，registry 與套件來源可能受到政策限制。不要為了測試方便而永久加入不明鏡像，也不要以關閉憑證驗證的方式解決下載問題。來源、憑證與代理路徑都應該可以被團隊成員理解和重現。

Docker Hub 與 Docker daemon 的代理配置

Docker 是開發者 VPN 配置中最容易被誤判的部分。終端機已經能使用 Git，不代表 docker pull 一定成功，因為命令列只是 Docker CLI，而真正拉取映像檔的請求通常由 Docker daemon 發出。Docker Desktop、Linux 上的 systemd 服務，以及遠端 Docker daemon 的設定位置都不同。

如果使用 Docker Desktop，應先確認桌面應用程式本身是否能連線，再查看其代理設定與引擎設定。若使用 Linux daemon，則需在 daemon 所在的服務環境設定代理，並在修改後重新載入服務。代理設定應針對 daemon 的執行帳戶與服務環境生效，單純在目前 shell 執行 export 往往不足以影響背景服務。

# 先在目前終端機確認 Docker CLI 的基本狀態
docker info
docker pull IMAGE_NAME:TAG

出現錯誤時，可先觀察是 registry DNS 解析失敗、TLS 握手失敗、代理拒絕連線，還是映像檔本身不存在。若 Docker daemon 位於另一台機器，代理必須配置在那台機器的網路環境；本機 VPN 的代理連接埠不一定能被遠端 daemon 存取。這是許多「本機瀏覽器正常、遠端建置失敗」案例的根本原因。

鏡像、代理與快取不是同一件事

Docker Hub 加速可以透過代理、registry mirror 或團隊內部快取實現，但三者的管理責任不同。代理是讓 daemon 經由指定通道請求外部 registry；registry mirror 是將部分映像檔請求導向另一個鏡像服務；內部快取則可能在團隊網路中保存已拉取的層。不要把「設定了 VPN」描述成一定存在官方鏡像，也不要把任意第三方鏡像當成可信來源。

使用鏡像或快取前，應確認映像檔來源、更新策略、權限與簽章驗證方式。對生產環境而言，能否追蹤映像檔摘要比單純縮短下載時間更重要。開發環境可以先用代理驗證路徑，再依團隊需求建立受管理的 registry 或快取，避免所有工程師各自使用無法審核的來源。

動手配置：從連線到套件下載逐層驗證

建議不要一次修改所有工具。以下順序可以把問題分成 VPN 連線、代理監聽、域名解析、工具設定與目標服務五個層次。每完成一層，就記錄目前節點、協定、代理模式與錯誤訊息，之後更換設定時才有可比較的基準。

1. 先在官方客戶端或相容客戶端中匯入訂閱，選擇一個符合目標服務地區要求的節點，確認用戶端日誌沒有持續握手錯誤。
2. 查看客戶端提供的 HTTP、HTTPS 或 SOCKS 監聽資訊，使用一個不含帳戶密碼的測試請求確認代理連接埠可用。
3. 在終端機只設定目前工作階段的代理，分別測試 Git、npm 與 pip，不要先寫入全域設定。
4. 確認 Docker Desktop 或 Docker daemon 的實際執行位置，再將代理配置到真正發出 registry 請求的環境。
5. 測試完成後，逐項關閉代理或切換分流模式，確認哪些工具需要代理、哪些本地服務應該保持直連。
6. 最後再把已驗證的設定寫入使用者設定檔、團隊範本或 CI secret，並移除不再需要的明文代理資訊。

如果命令列工具仍然失敗，可以使用域名解析與 HTTPS 請求分開判斷。域名解析成功，只表示 DNS 回應可取得；TLS 握手成功，也不表示應用程式層的 registry 或 Git 權限一定正確。Docker 的錯誤日誌、Git 的詳細輸出、npm 的 verbose 日誌與 pip 的錯誤類型，應分別閱讀，不要只截取最後一行。

分流規則與 CI 建置的穩定做法

開發環境通常同時存在三類流量：需要經由 VPN 的國際服務、本地或企業內部服務，以及 Docker、資料庫、測試 API 等本機服務。全域代理雖然容易開始，但可能讓內部網域無法解析、localhost 請求繞路，或讓本地套件 registry 被錯誤轉送。較合理的方式是按網域、程序或目的地建立分流規則。

GitHub、Docker registry、npm registry 與 Python 套件索引是否應走代理，要依你的網路環境、服務政策與出口需求決定。規則應該使用明確的網域分類，並保留本機位址、區域網路和內部 DNS 的直連例外。若使用 Clash Verge 或 sing-box，可在規則組中分別處理代理、直連與拒絕；若使用官方客戶端，則依其提供的分流或應用程式代理功能設定。Shadowrocket 更適合在 iOS 上管理指定應用程式與規則，但不會替遠端 CI runner 自動配置代理。

CI runner 為什麼需要獨立配置

CI 建置可能在雲端 runner、公司自有主機或容器中執行。即使開發者電腦已經連線，CI runner 仍是另一個網路環境，必須獨立取得代理、憑證與套件來源設定。建議將代理網址、必要的 registry 登入資料放在 CI 的 secret 或受保護變數中，不要寫入公開工作流程檔案、Dockerfile 或建置日誌。

若在建置階段使用 Docker，還要區分「建置容器內的環境變數」與「拉取基礎映像檔的 daemon 代理」。前者隻影響容器內執行的 npm、pip 或其他命令；後者影響 runner 在建置開始前取得基礎映像檔的流程。兩者都需要設定時，應分別驗證，並確認代理設定不會被打包進最終映像檔層或被 docker history 等資訊暴露。

CI 也不適合盲目使用永不更新的固定節點。訂閱更新、節點變更與故障轉移都應由受控流程處理；同時保留可讀的錯誤輸出，讓團隊能區分代理不可達、registry 拒絕、套件鎖檔衝突與程式碼本身的測試失敗。穩定的建置依賴可重現的來源與版本，不是單純增加代理層數。

安全檢查與常見故障排查

開發者經常處理原始碼、存取權杖、套件憑證與容器 registry 登入資料，因此 VPN 配置不能只追求「能下載」。先確認用戶端來源可信，檢查它要求的系統權限是否與網路功能相符；再保護帳戶密碼、訂閱連結、Git token、npm token 和私有 registry 憑證。截圖或回報錯誤時，應遮蔽訂閱網址、QR Code、Authorization header、環境變數與完整命令列參數。

• ✅ 將 VPN 帳戶密碼與程式碼平台、套件平台的密碼分開使用。
• ✅ 把代理憑證放入受保護的環境變數或 secret 管理，不要提交到 Git。
• ✅ 更新訂閱後檢查規則是否仍保留本地服務與內部網域的直連。
• ✅ 更換節點後重新測試 DNS、Git、Docker、npm 與 pip，不要假設所有結果同步改變。
• ❌ 不要把未知的 Docker 鏡像、套件鏡像或線上轉換工具視為可信來源。
• ❌ 不要以關閉 TLS 憑證驗證、停用 SSH 主機檢查或公開 token 來快速排錯。

可以按照故障階段建立排查順序。若客戶端本身無法握手，先檢查本地網路、協定、節點與時間；若客戶端已連線但代理連接埠無法使用，檢查系統代理與防火牆；若代理可用但工具失敗，檢查工具自身的 proxy 語法、registry、DNS 與憑證；若只有 CI 失敗，則回到 runner 的執行位置、secret 和 daemon 設定。

當所有工具同時失敗時，不要先逐一重裝 npm、pip 或 Docker。先確認 VPN 客戶端是否仍顯示有效連線，再測試代理監聽是否存在，最後才查看目標服務。當只有一個工具失敗，則更可能是該工具的設定、憑證、版本或私有來源問題。這種由外而內的順序，通常比反覆更換節點更容易找出真正原因。