Claude Code 搭配 v2rayN：中國終端機連線設定攻略

想在中國大陸的終端機使用 Claude Code，卻遇到登入頁面載入失敗、套件下載逾時、API 請求被中斷，或模型回應到一半就停止？這些現象不一定代表 Claude Code 本身故障，也可能是終端機沒有使用 v2rayN 的代理、代理連接埠填錯、DNS 解析路徑不一致，或只有瀏覽器套用了代理而命令列仍然直連。本文以 Windows 上的 v2rayN 為主要示範，說明如何匯入訂閱、確認 Xray 核心、找出本機 HTTP 與 SOCKS 連接埠，並為 Claude Code、Node.js 與套件管理工具建立可檢查、可撤銷的代理設定。

Claude Code 的終端機流量通常不只包含模型請求。首次登入可能需要開啟瀏覽器完成授權，npm 或其他套件管理工具需要存取套件註冊站，命令列工具也可能連線至不同的 API、登入與遙測網域。因此，「瀏覽器可以開啟網頁」不能直接證明 Claude Code 的代理已設定完成。本文會將瀏覽器代理、終端機環境變數、Node.js 程序和 v2rayN 路由分開檢查，避免修改一個地方卻誤以為所有程式都已經接管。

本文速覽

本文適合已安裝或準備安裝 Claude Code，並使用 v2rayN 管理節點的 Windows 使用者。讀完後，你可以確認 v2rayN 的本機代理入口，為目前終端機設定 HTTP、HTTPS 或 SOCKS5 代理，測試登入與套件下載，並透過網域分流判斷究竟是節點、DNS、環境變數還是應用程式本身造成失敗。

先理解 Claude Code 與 v2rayN 的連線層次

v2rayN 本身不是所有程式都會自動使用的全域代理。它啟動 Xray 核心後，通常會在本機監聽 HTTP、SOCKS 或其他入站連接埠；應用程式必須透過系統代理、環境變數、TUN 模式或程式內建設定，才能將流量交給這些入口。Claude Code 在終端機中執行時，最容易忽略的正是這一步：桌面瀏覽器可能已經跟隨系統代理，但 PowerShell、Command Prompt、Windows Terminal 或整合式開發環境中的程序不一定會讀取相同設定。

Claude Code 發起請求終端機讀取代理本機代理入口Xray 路由判斷節點建立出站

在一般 HTTPS 請求中，終端機通常只需要一個可用的 HTTP CONNECT 代理即可。若工具明確支援 SOCKS5，也可以使用 v2rayN 的 SOCKS 入口；但不要把 SOCKS 連接埠填到只接受 HTTP 代理的欄位，也不要把本機監聽連接埠誤當成遠端節點連接埠。實際數值必須以 v2rayN「設定」→「參數設定」→「Core 基礎設定」或主視窗顯示的代理設定為準，常見範例可能是 HTTP 127.0.0.1:10809、SOCKS 127.0.0.1:10808，但不同版本與使用者設定可以不同。

HTTP 代理

位址: 127.0.0.1
常見連接埠: 10809
適用場景: HTTPS、npm、一般命令列

優先確認 v2rayN 實際顯示的 HTTP 入站連接埠，再填入環境變數。

SOCKS5 代理

位址: 127.0.0.1
常見連接埠: 10808
適用場景: 支援 SOCKS 的工具

若工具只接受 HTTP 代理，不要直接填入 SOCKS5 入口。

安裝 v2rayN 並準備可用節點

先從本站的安裝包頁面取得與系統架構相符的 v2rayN 版本，解壓後啟動主程式。首次啟動時，先不要急著設定 Claude Code，應先確認 v2rayN 可以單獨完成節點連線。若主程式沒有啟動 Xray 核心，或節點清單只有名稱而沒有有效參數，後續所有終端機測試都會失去意義。

啟動 v2rayN
解壓後執行主程式，查看主視窗底部的核心狀態與本機代理連接埠。若 Windows 防火牆跳出權限提示，確認規則只套用到需要的網路範圍。
新增訂閱
進入「訂閱分組」→「訂閱分組設定」→「新增」，貼上訂閱網址並儲存。訂閱網址含有授權資訊，請勿貼到公開聊天或錯誤回報中。
更新節點
回到「訂閱分組」選取來源，執行「更新訂閱」或相近指令。確認清單出現最新節點，並留意是否顯示解析失敗或內容為空。
啟用核心
選取一個節點後執行「設為活動伺服器」，再啟用系統代理。若只想讓終端機使用代理，也可以暫時不開系統代理，改用後文的環境變數方式。
記錄入口
在「設定」→「參數設定」中確認 HTTP 與 SOCKS 監聽位址。保留目前連接埠，例如 127.0.0.1:10809，後續測試必須使用相同數值。

節點測試成功只代表 v2rayN 能夠透過該節點建立測試請求，不代表 Claude Code 已經讀取代理設定。建議先用瀏覽器確認一個需要代理的 HTTPS 網站，再在同一個終端機視窗中進行命令列測試。若節點本身就無法連線，應先查看 Xray 日誌中的握手、DNS、連接埠或 TLS 錯誤，不要先修改 Claude Code 的登入設定。

結論：先驗證本機入口，再驗證應用程式

Claude Code 失敗時，最有價值的第一個問題不是「換哪個模型」，而是「目前這個終端機程序能否透過 127.0.0.1 的代理連接埠完成一個普通 HTTPS 請求」。入口未通，修改帳戶或模型參數都不會產生效果。

在終端機設定 Claude Code 的代理

Windows PowerShell 與 Command Prompt 的環境變數語法不同，設定前先確認你使用的終端機類型。代理網址可以使用 http://127.0.0.1:10809；即使目標是 HTTPS 網站，HTTP 代理也會透過 CONNECT 建立加密通道。只有在工具明確支援 SOCKS5 時，才改用 socks5://127.0.0.1:10808。若 v2rayN 的實際連接埠不是這兩個數值，必須替換為主視窗顯示的值。

# PowerShell：只對目前視窗有效
$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:NO_PROXY="localhost,127.0.0.1"

# 查看目前值
Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY

如果使用 Command Prompt，可以使用以下語法：

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set NO_PROXY=localhost,127.0.0.1
set HTTP_PROXY
set HTTPS_PROXY

這些設定只影響目前的終端機程序以及從該程序啟動的子程序。關閉視窗後，PowerShell 中以 $env: 設定的值通常不會保留。這種方式適合先驗證連線，因為測試失敗時容易清除，不會影響其他應用程式。確認可用後，再決定是否透過 Windows 使用者環境變數或專案啟動腳本長期套用；不建議將包含金鑰的完整命令寫進公開專案檔案。

設定環境變數後，先用一般 HTTPS 請求測試代理，而不是立即啟動 Claude Code：

# PowerShell
Invoke-WebRequest https://example.com -UseBasicParsing

# 若系統有 curl，也可指定代理
curl.exe -I -x http://127.0.0.1:10809 https://example.com

若普通請求可以完成，卻只有 Claude Code 失敗，下一步才應查看 Claude Code 的登入流程、Node.js 版本、API 權限與應用程式支援的代理變數。部分工具只讀取大寫變數，部分工具會同時檢查小寫變數；遇到行為不一致時，可在目前視窗同時設定 http_proxy 與 https_proxy，但不要為同一變數寫入互相衝突的兩個值。

首次使用 Claude Code 時，登入流程可能會呼叫瀏覽器，也可能由終端機顯示一次性連結或驗證提示。瀏覽器可以開啟登入頁，不代表回到終端機後的回呼、權杖交換與 API 請求都沿用同一代理。登入期間應保持 v2rayN 節點與本機代理入口穩定，不要在瀏覽器已開啟授權頁後立刻切換節點或重新啟動核心，否則一次性流程可能過期。

如果錯誤發生在套件下載階段，請分開檢查 npm 的代理設定與目前環境變數。npm 可能保存過期的代理值，即使 v2rayN 已改用另一個連接埠，npm 仍然嘗試連線到舊入口。可先查看設定：

npm config get proxy
npm config get https-proxy
npm ping

若確認要讓 npm 使用目前的 HTTP 代理，可以在本機使用者設定中寫入一致值；若只想暫時測試，則優先使用環境變數，測試完成後再清理舊設定。當 npm 回報 ECONNREFUSED 127.0.0.1:10809，通常表示本機沒有程序監聽該連接埠、v2rayN 已關閉，或實際 HTTP 入口不是 10809。若是 ETIMEDOUT，則可能是節點、遠端註冊站、DNS 或上游網路路徑逾時，不能只把連接埠改成另一個數字。

現象	優先檢查	判斷方向
瀏覽器可登入，終端機逾時	HTTP_PROXY、HTTPS_PROXY	終端機未繼承系統代理，或變數指向錯誤入口
ECONNREFUSED 127.0.0.1	v2rayN 核心與本機連接埠	本機代理未啟動、連接埠被修改或被其他程序占用
npm ping 失敗	npm proxy、DNS 與套件站連線	npm 保存舊代理，或目前節點無法存取註冊站
模型回應中斷	節點穩定性、TLS 與長連線	短請求可通，但長時間 HTTPS 串流受到丟包或重置影響

為 AI 開發流量設計分流與 DNS

不建議把所有流量無條件送進代理。Windows 更新、區域網路服務、內部 Git 伺服器與本機管理頁面通常應直連；Claude Code 登入、模型 API 與必要套件註冊站則需要依目前網路條件選擇可達的出站。v2rayN 的路由規則由 Xray 核心執行，順序很重要：私有位址與明確直連例外應放在前面，代理網域規則放在中段，最後才使用代理兜底。

本機與內網：將 geoip:private 與公司內部網域交給直連，避免終端機連線到本機服務時繞行遠端節點。
套件來源：對 npm、PyPI 或其他實際使用的註冊站逐一測試，不要只根據網域名稱猜測應該直連或代理。
模型與登入網域：若某個網域在目前網路下直連不穩，應由代理出站處理；具體網域以 Claude Code 當前版本的官方說明與日誌為準。
DNS 路徑：若節點網域解析失敗，先確認 v2rayN 的 DNS 設定與路由策略，避免本地解析結果將請求導向不可達位址。

使用 TUN 模式時，應特別留意 DNS 是否也由同一處理鏈接管。只有設定了終端機環境變數，並不能處理不遵循該變數的程序；只有開啟 TUN，也不代表所有 DNS 與應用程式流量都一定按照預期分流。排查時可先關閉複雜規則，只保留一個可用代理出站與一個直連出站，確認基本請求成功後再逐步加入 geosite、geoip 和自訂網域例外。

依錯誤類型完成最後檢查

當 Claude Code 顯示登入失敗或請求中斷時，先記錄時間、目前節點、v2rayN 核心狀態與終端機使用的代理值，再一次只改一個條件。若切換節點後恢復，應比較兩個節點的延遲、丟包、TLS 傳輸與長連線穩定性，而不是只記住「某個名稱可以用」。若所有節點同時失敗，則要優先檢查本機時間、訂閱更新、代理入口與 DNS。

我已開啟系統代理，為什麼終端機仍然逾時？

先在同一個終端機執行 Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY，確認程序是否真的取得代理變數。若變數為空，暫時手動設定 127.0.0.1 與 v2rayN 實際 HTTP 連接埠再測試。

HTTP 代理和 SOCKS5 到底該選哪個？

優先使用工具文件明確支援的類型。Claude Code 或 npm 若以 HTTP 代理環境變數運作，先填 HTTP 入口；只有確認工具支援 SOCKS5 時，才使用 SOCKS 連接埠。

npm 顯示本機連接埠拒絕連線怎麼辦？

檢查 v2rayN 是否仍在執行、核心是否已啟動，以及 npm 保存的 proxy 與 https-proxy 是否指向舊連接埠。修正後重新開啟終端機再執行 npm ping。

模型可以回應，但長內容常常中斷？

先換一個延遲較低且丟包較少的節點，並查看 Xray 日誌是否出現連線重置或 TLS 錯誤。短暫成功只能證明請求能建立，不能證明串流連線足夠穩定。

完成設定後，建議按「普通 HTTPS 請求 → npm ping → Claude Code 登入 → 簡短模型請求 → 較長程式碼工作」的順序驗證。每一步都應在同一個終端機視窗、同一個 v2rayN 節點和同一組代理變數下進行。若中途更換節點、修改路由或重啟核心，應重新記錄條件，否則最後得到的結果無法對應到實際變更。