Gemini CLI 搭配 v2rayN：中國大陸連線設定教學

想在中國大陸使用 Gemini CLI，卻遇到登入失敗、API 請求逾時，或瀏覽器能開啟服務但終端機無法連線？這類問題通常不是單一節點失效，而是 v2rayN 的代理入口、命令列環境變數、DNS 解析方式與 Gemini CLI 的驗證流程沒有接在同一條路徑上。瀏覽器能使用代理，也不代表命令列程式會自動繼承相同設定。

本文以 Windows 桌面環境為主，從 v2rayN 安裝、訂閱匯入與節點選擇開始，逐步確認本機代理連接埠，再設定 Gemini CLI 需要的環境變數與分流規則。文中的連接埠以常見的 HTTP 代理 10809 為例；你的版本或自訂設定可能不同，請以 v2rayN「設定」→「參數設定」→「Core 基礎設定」中顯示的實際值為準。

本文速覽

本文適合第一次把 Gemini CLI 接到 v2rayN 的使用者，會說明節點與代理模式的選擇、Windows 終端機環境變數、PowerShell 測試方法、API 金鑰安全，以及遇到登入或請求錯誤時如何分層排查。

4 層

安裝、代理、認證、分流

10809

常見 HTTP 代理連接埠

3 項

連線前檢查指標

2026

本文操作環境年份

先準備 v2rayN 與可用的代理節點

Gemini CLI 發出的請求會由目前使用的終端機程序建立。v2rayN 必須先啟動核心並提供本機代理入口，命令列工具才有可能透過它連到外部服務。因此，第一個目標不是立刻執行 Gemini CLI，而是確認 v2rayN 本身已有一個可用節點，且核心狀態正常。

取得安裝包
前往安裝包頁面選擇對應 Windows 架構的 v2rayN 版本，解壓至不含特殊字元的資料夾，例如 C:\Tools\v2rayN。
匯入訂閱
開啟 v2rayN，進入「訂閱分組」→「訂閱分組設定」→「新增」，貼上訂閱網址後儲存，再執行「更新訂閱」。訂閱網址包含存取憑證，不要貼到公開記事或聊天群組。
選擇節點
在伺服器清單選擇更新後的節點，執行延遲或可用性測試，再使用「設為活動伺服器」。清單中看得到節點，不代表它已成為目前出口。
啟動代理
確認 Xray 或其他目前指定的核心已啟動，接著在主視窗啟用「系統代理」。若只想讓終端機使用代理，也可以先不開系統代理，改用後文的環境變數方式。

節點協定可以是 VLESS、VMess 或其他訂閱提供的格式，但 Gemini CLI 是否能穩定工作，主要取決於代理鏈路是否能建立 HTTPS 連線，而不是單純看節點名稱。建議先使用一個延遲穩定、丟包較低的節點，不要在測試命令列時同時變更核心、節點與路由設定。

v2rayN 本機入口

HTTP 代理: 依實際設定，常見為 10809
SOCKS 代理: 依實際設定，常見為 10808
核心狀態: 已啟動且無端口占用

不要直接假設連接埠固定，請以 v2rayN 設定頁顯示值為準。

Gemini CLI 連線方式

優先入口: HTTPS_PROXY
備用入口: HTTP_PROXY、ALL_PROXY
驗證資料: OAuth 或 API 金鑰

代理環境變數只影響命令列程序，不會自動改寫節點設定。

確認 HTTP 代理與終端機可以互通

v2rayN 的系統代理開關與命令列環境變數是兩個不同層次。系統代理通常會修改 Windows 的使用者代理設定，能被部分桌面程式讀取；PowerShell、命令提示字元與 Node.js 程式是否採用它，則取決於程式本身的實作。為了避免判斷錯誤，建議明確設定 HTTPS_PROXY，讓 Gemini CLI 知道 HTTPS 請求應送往哪個本機代理入口。

先在 v2rayN 的「設定」→「參數設定」查看 HTTP 代理連接埠。假設顯示為 10809，可在 PowerShell 中設定目前視窗有效的環境變數：

$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
$env:ALL_PROXY = "http://127.0.0.1:10809"

ALL_PROXY 並不是所有程式都會使用，但部分命令列工具會讀取它。若你的 v2rayN 只提供 SOCKS 入口，則應按照程式支援情況使用 socks5://127.0.0.1:10808；不要把 SOCKS 連接埠誤填成 HTTP 代理。Gemini CLI 或其底層套件若對 SOCKS 支援不完整，優先使用 v2rayN 提供的 HTTP 代理入口通常較容易排查。

設定完成後，先不要急著登入 Gemini CLI，可以用 PowerShell 檢查代理是否真的能轉送 HTTPS：

curl.exe -I https://generativelanguage.googleapis.com
curl.exe -I https://www.google.com

若回應包含 HTTP 狀態碼，例如 200、301 或其他由遠端服務回傳的狀態，代表本機到代理入口及代理到目標的基本路徑已經建立。若顯示「無法連線到 127.0.0.1:10809」，先回到 v2rayN 檢查核心是否啟動、連接埠是否正確，以及是否被其他程式占用。若本機代理可連線但遠端持續逾時，則應測試其他節點，而不是反覆修改 Gemini CLI 的認證資料。

結論：先驗證代理，再處理登入

只有當 curl.exe 能透過目前的代理入口取得遠端 HTTPS 回應後，才值得繼續排查 Gemini CLI 的 OAuth、API 金鑰或模型權限；否則登入錯誤很可能只是網路請求沒有抵達服務端。

安裝 Gemini CLI 並設定命令列環境

Gemini CLI 的安裝方式與版本要求可能隨發布版本調整，建議先依官方安裝說明取得目前支援的 Node.js 與 CLI 版本，再在 PowerShell 中完成安裝。若使用 npm，常見流程會是先確認 Node.js 與 npm 可執行，再安裝或更新 Gemini CLI。實際套件名稱與登入指令請以你取得的版本文件為準，不要把網路文章中的舊參數直接套用到新版本。

node --version
npm --version
gemini --help

環境變數只在目前 PowerShell 視窗設定時，關閉視窗後就會消失。確認代理可用後，可以使用 Windows 使用者環境變數永久保存設定：

[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://127.0.0.1:10809", "User")
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:10809", "User")
[Environment]::SetEnvironmentVariable("ALL_PROXY", "http://127.0.0.1:10809", "User")

執行後要關閉並重新開啟終端機，已經存在的 PowerShell 程序不一定會讀到新值。若電腦上有公司代理、其他開發工具或舊的 HTTP_PROXY 設定，也要檢查是否與 v2rayN 入口衝突。可使用以下命令查看目前視窗實際採用的值：

Get-ChildItem Env:HTTP_PROXY
Get-ChildItem Env:HTTPS_PROXY
Get-ChildItem Env:ALL_PROXY

認證方式通常分為互動式登入與 API 金鑰兩類。互動式登入可能需要命令列開啟瀏覽器，或提供一次性驗證流程；若瀏覽器成功開啟但回到 CLI 後仍顯示失敗，應先確認完成登入的瀏覽器與執行 CLI 的終端機是否使用同一個使用者環境。API 金鑰則應依工具要求放在指定環境變數中，並避免直接寫進批次檔、Shell 設定檔或會同步到雲端的專案資料夾。

若必須暫時在目前視窗放入金鑰，可使用環境變數而不是將金鑰直接貼在命令列參數中。命令列歷史、工作列工具或終端機記錄可能保存完整命令。完成測試後，可關閉終端機，並依金鑰管理服務的功能撤銷不再使用的金鑰。

為 Gemini CLI 設定適合的分流規則

Gemini CLI 通常不只連線一個網域。登入、API 呼叫、模型服務、套件下載與時間驗證可能使用不同的主機名稱。若只把某一個網域加入代理規則，登入頁可能可以開啟，但實際生成請求仍然逾時。初次配置時，建議先讓命令列的 HTTPS 請求統一經過代理，確認整條鏈路正常後，再依日常需求收窄分流範圍。

如果使用 v2rayN 的系統代理模式，規則應放在「規則設定」或對應的路由設定頁中，並確保代理出站是活動出口。若使用 TUN，還要確認終端機程序產生的 DNS 查詢與 TCP 流量確實被 TUN 接管；只開啟 TUN 介面卻沒有正確的 DNS 或路由規則，可能出現瀏覽器正常、CLI 仍然失敗的情況。

第一層：本機與區域網路位址使用直連，避免把 127.0.0.1、路由器管理位址或本地服務送到遠端節點。
第二層：中國大陸常用網站與套件鏡像依需求直連，減少不必要的代理延遲。
第三層：Gemini CLI 實際使用的外部服務網域交給代理出站，不要只依賴單一固定主機名稱。
第四層：未命中的 HTTPS 流量可先採代理兜底，待確認清單後再調整為更細的策略。

若使用 geosite 與 geoip 分流，請留意規則順序。geoip:private 應放在一般規則之前；針對服務網域的代理規則要放在寬泛的直連規則之前，最後才放預設代理或直連。規則命中與否還會受到 DNS 模式、domainStrategy、嗅探和核心版本影響，因此修改後要重新啟動核心，並從日誌確認實際出站標籤。

瀏覽器能登入，CLI 卻顯示逾時？

先在同一個 PowerShell 視窗檢查 HTTPS_PROXY，再用 curl.exe -I 測試。瀏覽器使用系統代理，不代表 CLI 已讀取相同設定。

設定環境變數後仍然沒有作用？

關閉原本的終端機並重新開啟；若從 IDE 內建終端機執行，也要重新啟動 IDE，讓程序取得新的使用者環境。

登入成功但模型請求失敗怎麼辦？

檢查模型權限、配額與 API 金鑰狀態，再查看 v2rayN 日誌是否只有特定服務網域被直連或解析失敗。

HTTP 與 SOCKS 代理該選哪個？

優先使用 v2rayN 提供且能被 CLI 明確支援的 HTTP 代理；HTTP 入口常見為 10809，但仍以本機設定為準。

依錯誤層級排查登入與 API 請求

當 Gemini CLI 顯示錯誤時，先保留完整錯誤文字與發生時間，不要立刻清除認證資料或重新匯入訂閱。可以把問題分成四層：v2rayN 核心是否運作、代理連接埠是否可達、遠端服務是否回應，以及 Gemini CLI 的認證或權限是否正確。每次只修改一層，結果才容易判斷。

報錯：connect ECONNREFUSED 127.0.0.1:10809

原因與解法:CLI 嘗試連接的本機 HTTP 代理沒有監聽，或環境變數填錯連接埠——回到 v2rayN 查看實際 HTTP 入口，啟動核心後重新設定 HTTPS_PROXY。

報錯：ETIMEDOUT 或 request timeout

原因與解法:代理到遠端服務的路徑逾時，可能是節點品質、路由命中或 DNS 問題——先更換已測試可用的節點，再查看 Xray 日誌中的目標網域與出站。

報錯：401 Unauthorized

原因與解法:服務端已收到請求，但認證資料無效、過期或沒有目標模型權限——重新確認登入帳戶或 API 金鑰，並檢查配額與專案設定。

報錯：CERTIFICATE_VERIFY_FAILED

原因與解法:本機時間、憑證鏈或攔截式網路環境造成 TLS 驗證失敗——先校準系統時間，不要為了繞過錯誤而關閉憑證驗證。

完成基礎配置後，可用一個簡短、低成本的請求測試，不要一開始就執行長上下文或大量輸出的任務。觀察 v2rayN 日誌是否出現新的連線、目標主機與正常關閉記錄，再對照 CLI 回應時間。若命令列可以成功完成簡短請求，才表示代理、認證與基本模型呼叫大致接通；之後的速度差異，才值得從節點負載、模型服務狀態與本機網路品質分析。

現象	優先檢查	不要先做的事
無法連到 127.0.0.1	v2rayN 核心、HTTP 連接埠、環境變數	重新建立 API 金鑰
遠端請求逾時	節點、DNS、規則命中與出站日誌	反覆刪除 CLI 認證快取
401 或權限錯誤	帳戶、金鑰、專案與模型權限	只更換代理節點
TLS 憑證錯誤	系統時間、代理鏈與憑證驗證	關閉 TLS 驗證

最後，建議把穩定配置記錄下來：v2rayN 使用的核心類型、HTTP 代理實際連接埠、PowerShell 中的環境變數名稱、Gemini CLI 使用的認證方式，以及分流規則的修改日期。節點或訂閱更新後，先重新測試 curl.exe 和一個簡短 CLI 請求，再進行長時間工作。這樣即使日後遇到登入失敗，也能快速判斷是代理路徑、服務端認證，還是規則變更造成的問題。