Gemini CLI 在中國大陸怎麼用？v2rayN 終端代理設定

先理解 Gemini CLI 為什麼會連線失敗

Gemini CLI 是在終端機中執行的命令列工具。它和瀏覽器最大的不同，是它不一定會自動沿用瀏覽器的代理設定。即使你已經在 v2rayN 中開啟系統代理，瀏覽器可以正常開啟網頁，Gemini CLI 仍可能出現登入頁面無法載入、授權流程中斷、API 請求逾時或無法解析主機名稱等問題。

在中國大陸網路環境中，實際連線結果還會受到 DNS、網路出口、帳戶地區、Google 服務可用性以及本機安全軟體影響。因此，不能把所有錯誤都簡單歸結為「v2rayN 速度不夠快」。更有效的做法，是先拆分成三段：v2rayN 是否有可用節點、終端機是否真的使用了本機代理、Gemini CLI 所需的登入或 API 網域是否被正確轉送。

本文只討論用戶端與終端代理的技術設定。Gemini 服務的使用資格、帳戶所在地區、API 條款與當地法律法規，仍應以官方要求為準。代理工具不能取代有效帳戶，也不能保證某項服務在所有網路環境下都能使用。

在 v2rayN 匯入訂閱並確認節點

開始設定 Gemini CLI 之前，先把 v2rayN 本身跑通。開啟 v2rayN 後，新增你從服務提供者取得的訂閱位址，完成更新，確認節點列表中確實出現可選項目。如果你只有單條分享連結，也可以先用手動匯入方式測試。訂閱適合管理多個節點，單節點則適合快速判斷用戶端是否正常。

匯入完成後，不要只看節點名稱或旗標。先選一個延遲較低、近期測速結果穩定的節點，再在 v2rayN 中啟用它。若節點列表為空，應先排查訂閱位址是否複製完整、訂閱是否已到期、系統時間是否正確，以及目前網路能否取得訂閱內容。訂閱未成功時，後面設定終端環境變數也沒有意義。

若訂閱更新時提示下載失敗或逾時，可以先更換網路測試，例如改用手機熱點；也可以在 v2rayN 裡確認更新訂閱時是否需要代理。更新成功後仍無法連線，則要把「訂閱取得」與「節點代理」分開處理，不要反覆刪除程式或更換完全不同的客戶端。

先用系統代理建立可驗證的基線

Gemini CLI 的第一次設定，建議先使用 v2rayN 的系統代理，而不是一開始就啟用 TUN。系統代理的優點是變數較少，容易確認本機 HTTP 或 SOCKS 監聽埠，也不會立即引入虛擬網卡、路由衝突與管理員權限等額外問題。等終端代理穩定後，如果有其他不遵循代理的應用程式，再考慮 TUN。

在 v2rayN 的設定中，記下本機 HTTP 代理與 SOCKS 代理的實際埠號。不同版本、不同設定檔的埠號可能不一樣，不要直接照抄網路文章中的固定數字。常見情況是 HTTP 代理和 SOCKS 代理各自使用不同埠號；Gemini CLI、Node.js 或登入工具對代理協定的支援也可能不同，因此優先使用程式明確支援的 HTTP 代理。

設定完成後，先用瀏覽器確認 v2rayN 的節點確實可用，再確認終端機能否透過本機代理發出基本 HTTPS 請求。這一步的目的不是測試 Gemini，而是建立一個簡單基線：如果連最基本的網路請求都失敗，問題應留在 v2rayN、節點、代理埠或本機防火牆，不要急著修改 Gemini CLI 的登入設定。

在終端機設定 HTTP_PROXY 與 HTTPS_PROXY

命令列程式最常見的代理方式，是讀取環境變數。請先從 v2rayN 介面取得實際的本機 HTTP 代理位址與埠號，然後在啟動 Gemini CLI 的同一個終端工作階段中設定 HTTP_PROXY 與 HTTPS_PROXY。HTTPS 請求通常仍然使用 HTTP 代理來建立 CONNECT 通道，所以不要看到 HTTPS 就自行改成不存在的協定。

在 Windows PowerShell 中，可以使用 $env:HTTP_PROXY="http://127.0.0.1:本機埠號" 與 $env:HTTPS_PROXY="http://127.0.0.1:本機埠號"。這種設定只對目前開啟的 PowerShell 視窗有效，關閉視窗後不會永久保留，適合先做測試。若測試確認可行，再決定是否透過 Windows 的使用者環境變數長期保存。

在傳統命令提示字元中，可以使用 set HTTP_PROXY=http://127.0.0.1:本機埠號 與 set HTTPS_PROXY=http://127.0.0.1:本機埠號。如果你使用 Git Bash，則可用 export HTTP_PROXY=http://127.0.0.1:本機埠號 與 export HTTPS_PROXY=http://127.0.0.1:本機埠號。重點不是照搬埠號，而是把範例中的「本機埠號」替換成 v2rayN 當前顯示的實際值。

部分工具也會讀取小寫形式的 http_proxy、https_proxy，或通用的 ALL_PROXY。如果大寫變數沒有作用，可以在同一個終端中補充小寫變數，但不要同時填入多組互相矛盾的代理位址。環境變數越多，越難判斷程式到底使用了哪一組設定。

用基本請求驗證終端代理

設定環境變數後，先不要直接判斷 Gemini CLI 成功或失敗。可以使用系統已有的 curl，向一個你平常能存取的 HTTPS 網站發出請求，並觀察是否能在合理時間內收到回應。若命令列工具提供代理參數，也可以先以明確指定代理的方式測試，這能排除環境變數尚未被目前工作階段讀取的可能。

如果瀏覽器可以連線，但 curl 仍然逾時，先檢查四件事。第一，v2rayN 是否仍在執行且節點處於啟用狀態。第二，代理埠是否抄錯，或被其他程式占用。第三，Windows 防火牆或安全軟體是否阻止終端程式存取本機代理。第四，目前開啟的終端視窗是否真的包含剛才設定的環境變數。

如果基本請求可以成功，而 Gemini CLI 仍登入失敗，問題範圍就縮小了。此時可能是 CLI 使用了不同的 Node.js 網路模組、登入流程需要額外的瀏覽器回呼、帳戶授權受到地區限制，或某些 API 網域沒有按照預期走代理。不要立即提高代理層級，先查看終端顯示的完整錯誤訊息和請求階段。

為 Gemini CLI 設計清楚的路由策略

在 v2rayN 中，路由模式會影響不同網域是直連還是代理。若使用規則模式，Gemini CLI 所需的登入、API、套件或授權網域可能被分到不同出口。瀏覽器能開啟某個頁面，不代表命令列中的所有請求都會使用同一條路徑。遇到登入頁面載入不完整或 API 逾時時，應先暫時使用較容易驗證的代理模式，再逐步收窄規則。

測試階段可以先使用全域代理確認整體鏈路，成功後再切換回規則模式。這樣做的價值在於建立對照組：全域代理成功而規則模式失敗，通常表示路由規則、DNS 分流或網域匹配需要調整；兩者都失敗，則更可能是節點、帳戶或代理協定問題。

若你使用 TUN，還要額外注意 DNS 接管、虛擬網卡優先順序，以及其他 VPN 或代理工具是否同時執行。TUN 可能讓更多程式被接管，但不代表所有問題都會自動消失。對 Gemini CLI 這類明確可以設定環境變數的工具，先用 HTTP 代理跑通，通常比直接依賴 TUN 更容易維護。

登入失敗與請求逾時的排查順序

遇到登入失敗時，先看錯誤屬於哪一類。若提示無法解析主機名稱，優先檢查 DNS 與路由；若提示連線逾時，檢查節點品質、代理埠與終端環境變數；若瀏覽器授權成功但 CLI 回呼失敗，則要檢查登入流程是否需要本機瀏覽器、回呼埠是否被防火牆阻擋，以及終端是否在同一個使用者環境中執行。

若請求偶爾成功、偶爾逾時，不要只看平均延遲。命令列 AI 工具通常會連續發出多個請求，還可能傳輸較大的提示內容，因此節點的丟包率、TLS 建立時間和長連線穩定性都很重要。可以換一個節點重試，並在 v2rayN 中比較多個節點的實際表現，而不是只選名稱看起來最近的節點。

如果錯誤訊息涉及 API 金鑰、帳戶權限、配額或服務地區，代理設定未必是根本原因。確認環境變數中的金鑰沒有多餘空格或換行，也不要把金鑰直接貼到公開日誌、截圖或程式碼儲存庫。必要時重新建立有效憑證，並依照官方文件確認 Gemini CLI 目前要求的登入方式。

  1. 確認 v2rayN 正在執行，且已選中可用節點
  2. 記下實際 HTTP 代理位址與埠號，不使用猜測值
  3. 在目前終端設定 HTTP_PROXY 與 HTTPS_PROXY
  4. 先用 curl 或其他基本請求驗證終端代理
  5. 先以全域代理建立對照，再檢查規則模式
  6. 最後檢查帳戶、金鑰、配額與登入回呼問題

常見問題

為什麼 v2rayN 已開啟系統代理，Gemini CLI 還是不能用？ 因為命令列程式不一定讀取作業系統代理。請在啟動 CLI 的終端中設定 HTTP_PROXY 與 HTTPS_PROXY，再用基本 HTTPS 請求確認環境變數確實生效。

應該使用 HTTP 代理還是 SOCKS 代理？ 先使用 v2rayN 顯示的 HTTP 代理，因為許多 Node.js 工具與命令列程式對 HTTP CONNECT 的支援較直接。只有在 Gemini CLI 或其執行環境明確支援 SOCKS 時，才改用 SOCKS 位址，並確認協定前綴與埠號都正確。

全域代理能用，規則模式不能用，代表什麼？ 這通常表示路由規則、DNS 分流或網域匹配不完整。可以逐步檢查登入與 API 請求使用的網域，先保留能工作的設定，再慢慢增加分流規則，避免一次修改太多項目。

設定代理後仍然無法登入，是不是一定要換 v2rayN？ 不一定。先確認節點、終端代理、帳戶憑證與服務要求。只有在最新版本、可用節點和正確環境變數都確認後，仍出現明確的相容性錯誤，才值得進一步檢查 CLI 版本與 Node.js 執行環境。

總結來說，Gemini CLI 的終端代理設定不只是打開 v2rayN 開關。比較穩妥的順序是：先匯入訂閱並驗證節點，再記下本機 HTTP 代理埠，接著在終端設定環境變數，最後用基本請求和全域代理建立可重現的測試基線。當登入失敗或請求逾時時，依序檢查代理鏈路、路由、DNS、帳戶與憑證，通常比反覆重裝用戶端更快找到真正原因。