開發者用 v2rayN 設定終端機代理：Git、npm 與 Docker 實戰

本文速覽

Git 複製失敗、npm 套件下載逾時與 Docker 映像檔拉不到，很多時候不是工具本身故障，而是終端機沒有使用 v2rayN 的本機代理。本文以 v2rayN 7.x 與常見的 Xray 核心為基準，從本機 HTTP、SOCKS 連接埠開始，逐步設定 Git、npm、Docker、IDE 與 AI 開發工具，並整理環境變數、憑證、DNS、容器網路及安全回復方法。完成後，讀者可以依工具需求選擇明確的代理方式，而不是把系統代理、終端機代理與容器代理混為一談。

先理解終端機代理的資料路徑

v2rayN 啟動核心後，通常會在本機建立 HTTP 與 SOCKS 代理入口。以常見設定為例，HTTP 代理監聽於 127.0.0.1:10809，SOCKS5 代理監聽於 127.0.0.1:10808。這兩個連接埠只是本機程式之間的入口，不是遠端節點的連接埠；終端機工具先連到本機入口，再由 Xray 核心依目前節點、DNS 與路由規則轉送至遠端。

瀏覽器能正常開啟網頁，不代表 Git、npm 或 Docker 也會自動使用相同代理。瀏覽器通常會讀取作業系統代理設定，但命令列工具各自有自己的代理優先順序：Git 會讀取自身設定與環境變數，npm 會讀取 npm 設定檔，Docker CLI 則通常依賴 Docker Engine 的服務設定。IDE 內建的終端機雖然看起來與一般命令提示字元相同，實際上仍可能繼承 IDE 啟動時的環境變數，而不是即時讀取 v2rayN 的系統代理。

v2rayN 啟動核心本機代理入口工具讀取設定請求進入核心節點轉送回應

10809

常見 HTTP 代理連接埠

10808

常見 SOCKS5 連接埠

3 層

系統、工具、容器設定

1 個

建議先驗證的可用節點

工具或環境	主要代理入口	設定重點	常見誤區
Git	HTTP、HTTPS、SOCKS	`git config` 或環境變數	只設定一個協定，另一個網址仍然失敗
npm	HTTP、HTTPS	`npm config set proxy`	忘記清除舊連接埠或錯誤的 registry
Docker	Docker Engine 服務代理	daemon 的代理環境與重啟	只在主機終端機設定，Docker 服務仍未取得設定
IDE	IDE 內建終端機或設定頁	重啟 IDE 以重新繼承環境變數	外部終端機正常，IDE 仍使用舊值

結論：先測本機入口，再設定各個工具

若 127.0.0.1:10809 或 127.0.0.1:10808 沒有程序監聽，Git、npm 與 Docker 的任何參數都不可能成功。先在 v2rayN 確認核心已啟動，再逐項測試工具，排錯範圍會小很多。

在 v2rayN 確認本機代理與終端機環境

本文操作基準為 2026 年的 v2rayN 7.x 介面。不同小版本可能將「參數設定」、「核心設定」或「本機代理」放在略有差異的分頁，但名稱通常相近。先更新訂閱、選取一個已確認可用的節點，並以系統代理模式完成一次瀏覽器測試。若瀏覽器本身也無法通過代理，應先處理節點、核心或 DNS 問題，不要直接進入 Git 與 Docker 的複雜設定。

確認核心啟動
開啟 v2rayN，選取可用節點並啟動核心。查看主視窗記錄，確認沒有 failed to start、address already in use 或設定欄位解析失敗等訊息。
查看本機連接埠
進入「設定」→「參數設定」→「本機代理」或相近分頁，記錄 HTTP 與 SOCKS 入口。本文範例使用 127.0.0.1:10809 與 127.0.0.1:10808，實際值以你的設定為準。
測試連接埠
在 PowerShell 執行 Test-NetConnection 127.0.0.1 -Port 10809，確認 TcpTestSucceeded 為 True。SOCKS 入口則將連接埠替換為 10808。
設定工作階段
在目前終端機設定 HTTP_PROXY、HTTPS_PROXY 與 ALL_PROXY，再使用 curl 進行外部 HTTPS 測試，確認請求確實經過 v2rayN。
重新啟動工具
完成環境變數設定後，關閉並重新開啟 IDE、終端機與 Docker Desktop。已經執行中的程序通常不會自動讀取後來新增的環境變數。

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:ALL_PROXY="socks5://127.0.0.1:10808"
curl.exe -I https://registry.npmjs.org/

如果測試成功，回應中的 HTTP 狀態可能是 200、301 或 302，重點是能在合理時間內收到伺服器回應。不要只用 ping 判斷代理是否有效，因為 ICMP 流量不一定會經過 HTTP 或 SOCKS 代理。若公司網路、公共網路或安全軟體攔截 TLS，還要區分是代理連線失敗，還是憑證驗證受到中間設備影響。

Git 與 npm 的實戰設定

Git 的遠端網址常見為 HTTPS，也可能使用 SSH。HTTP 代理最適合處理 HTTPS 形式的程式碼同步；若使用 SSH 遠端，不能單純把 http.proxy 當成 SSH 代理。初次排查時可先使用 HTTPS 遠端確認網路路徑，再決定是否需要為 SSH 另行設定 SOCKS 通道。設定 Git 代理時，建議先使用單一倉庫範圍，確認有效後再考慮寫入全域設定。

git config --local http.proxy http://127.0.0.1:10809
git config --local https.proxy http://127.0.0.1:10809
git config --local --get-regexp "http\..*proxy"

git -c http.proxy= clone https://example.invalid/team/project.git

上面的示例使用保留用途的網域，只展示命令形式。實際操作時，將最後一行替換成你的 HTTPS 遠端網址。若要取消目前倉庫的代理，可以執行 git config --local --unset http.proxy 與 git config --local --unset https.proxy。若先前曾在全域設定中留下錯誤值，應用 git config --global --get-regexp "http\..*proxy" 檢查，避免全域值覆蓋你以為已清除的本地設定。

npm 通常需要同時設定 HTTP 與 HTTPS 代理，並確認 registry 本身可用。代理網址使用 http:// 並不代表目標網站必須是 HTTP；它表示 npm 以 HTTP CONNECT 或相應方式連到本機代理，再由代理處理 HTTPS 目標。不要把 https://127.0.0.1:10809 當成固定寫法，除非本機代理入口確實配置了 TLS。

npm config set proxy http://127.0.0.1:10809
npm config set https-proxy http://127.0.0.1:10809
npm config get proxy
npm config get https-proxy
npm ping

如果套件下載仍然逾時，先檢查 npm config get registry 的結果，再檢查 npm 設定檔是否殘留舊的代理。不要一開始就提高逾時秒數；逾時只會讓失敗等待更久，無法修復錯誤連接埠、失效節點或 DNS 問題。當 v2rayN 停止時，若 npm 立刻出現 ECONNREFUSED 127.0.0.1:10809，代表 npm 確實讀到了代理設定，問題在於本機入口沒有服務，而不是 registry 語法。

Git HTTPS

HTTP 代理: http://127.0.0.1:10809
設定範圍: local 或 global
檢查命令: git config --get-regexp proxy
適合用途: 複製、拉取與推送 HTTPS 遠端

先用單一倉庫測試，確認成功後再擴大到全域設定。

npm 套件下載

HTTP 代理: http://127.0.0.1:10809
HTTPS 代理: http://127.0.0.1:10809
檢查命令: npm config get proxy
適合用途: npm ping 與套件安裝

代理設定與 registry 設定是兩件事，應分開測試與記錄。

Docker 映像檔與容器內網路

Docker 是最容易讓開發者誤判代理層級的工具。執行 docker pull 時，真正發出下載請求的通常是 Docker Engine，而不是目前的 PowerShell 或 IDE 終端機。因此，即使終端機中的 curl、Git 與 npm 都能通過 v2rayN，Docker Engine 仍可能因為沒有代理設定而無法拉取映像檔。

在 Windows 的 Docker Desktop 環境中，先確認 Docker Engine 已啟動，再於 Docker Desktop 的設定頁查看代理選項。若使用引擎服務的代理環境設定，應將 HTTP 與 HTTPS 代理指向主機可達的代理位址，儲存後重新啟動 Docker Desktop。主機上的 127.0.0.1 對 Docker Desktop 的實際可見性會依執行模式而不同；若引擎在獨立虛擬環境中執行，容器或引擎內的 loopback 不一定等於 Windows 主機的 loopback，遇到拒絕連線時不要只重試命令。

docker info
docker pull example.invalid/team/base:dev
docker run --rm alpine:3.20 wget -qO- https://example.invalid/health

上述命令中的映像檔與網域是示意值。先用 docker info 確認引擎可以回應，再執行實際的拉取操作。若 docker pull 報告 proxyconnect tcp: dial tcp 127.0.0.1:10809: connect: connection refused，表示 Docker Engine 嘗試使用本機代理，但目標環境沒有連到正在監聽的入口。若顯示 no such host，則要檢查引擎使用的 DNS；若是 context deadline exceeded，則應查看節點、registry 回應及代理逾時，而不是立即刪除映像檔快取。

映像檔拉取成功後，容器內執行的套件安裝又是另一層。Dockerfile 中的 RUN npm install、RUN apt-get update 或語言套件管理器，使用的是建置階段的環境；主機端 npm 的設定不會自動複製進容器。可以透過建置參數或專案專用設定傳入代理，但不應把帶有認證資訊的代理網址直接寫進公開 Dockerfile 或映像層，避免在歷史層與建置記錄中留下敏感資料。

docker build \
  --build-arg HTTP_PROXY=http://host-gateway:10809 \
  --build-arg HTTPS_PROXY=http://host-gateway:10809 \
  -t demo-app:local .

在容器執行階段，建議設定 NO_PROXY 排除資料庫、內部服務與本機網域，例如 localhost,127.0.0.1,.internal。不要把所有內部流量都送往外部代理，否則服務發現、區域網路連線與內部 API 可能被錯誤路由。若容器需要存取主機上的代理入口，還要依 Docker Desktop 的網路名稱與引擎支援方式調整主機位址，不能假設容器內的 127.0.0.1 就是主機。

測試位置	應檢查的代理	成功代表什麼
主機終端機	HTTP_PROXY、HTTPS_PROXY	目前工作階段能通過 v2rayN
Docker Engine	Docker Desktop 或服務代理	引擎可拉取 registry 映像檔
建置階段	Docker build args	Dockerfile 中的下載命令可連線
執行階段	容器環境變數與 NO_PROXY	應用程式依需求存取外部與內部服務

IDE、AI 工具與安全回復

IDE 通常同時包含內建終端機、套件索引、版本控制介面與遠端開發功能。這些功能不一定共用同一份代理設定。例如內建終端機可能繼承 HTTP_PROXY，但 IDE 的擴充功能仍依賴「設定」→「網路」中的獨立代理；版本控制介面則可能直接呼叫系統中的 Git 程序。因此，不能因為終端機執行 npm install 成功，就推論 IDE 的擴充功能也已經可以下載資料。

建議先在 IDE 的內建終端機執行 echo $env:HTTP_PROXY 或相應的環境查詢命令，再檢查 IDE 的網路設定是否明確指向 127.0.0.1:10809。修改後完整退出 IDE，再重新開啟專案。若只是關閉編輯器視窗而背景程序仍在，舊的環境變數可能仍被沿用。AI 輔助開發工具也應遵循相同原則：先確認它使用的是 IDE 網路設定、系統代理、命令列環境，還是自己的服務端點，再決定設定位置。

代理只應用於必要的開發流量。對公司內網、資料庫、版本控制內部域名與本機服務，應透過 NO_PROXY 或工具自身的排除清單直連。AI 請求、套件下載與程式碼同步可能包含專案名稱、錯誤訊息或原始碼片段，使用前應遵守所屬團隊的資料政策，不要因為代理已經可用，就把機密內容傳送到未核准的服務。

Git 顯示代理連線被拒絕，npm 卻正常？

先執行 git config --show-origin --get-regexp "http\..*proxy"，檢查 Git 是否仍指向舊連接埠；npm 與 Git 的設定彼此獨立，不能只看環境變數。

npm 設定了代理，為什麼仍然下載逾時？

依序執行 npm config get registry、npm config get proxy 與 npm ping，確認 registry、代理位址及節點都能單獨回應。

主機能用，Docker pull 卻失敗怎麼辦？

把排查重點移到 Docker Engine 的代理設定，儲存後重啟 Docker Desktop；主機終端機的環境變數不會自動套用到引擎服務。

關閉 v2rayN 後工具一直報本機拒絕連線？

清除 Git、npm、IDE 或工作階段中的代理值，或重新啟動工具。不要讓已停止的本機連接埠長期留在全域設定中。

完成工作後，可以依需要清除暫時環境變數。PowerShell 可使用 Remove-Item Env:HTTP_PROXY、Remove-Item Env:HTTPS_PROXY 與 Remove-Item Env:ALL_PROXY；Git 與 npm 則應分別取消設定。若只想讓單次命令使用代理，優先採用命令前綴或單一倉庫設定，避免把代理寫入團隊共用的專案檔案。Docker 的服務代理修改後，也要確認重啟已完成，再執行 docker info 與拉取測試。