Gemini CLI 在中國怎麼用？v2rayN 連線設定教學

先理解 Gemini CLI 需要哪些連線

Gemini CLI 是把 Gemini 的程式輔助能力帶進終端機的命令列工具。完成安裝後，你可以在終端機中提問、分析專案檔案、協助撰寫程式碼、解釋錯誤訊息，或讓工具根據目前工作目錄提供修改建議。對開發者來說，它比單純開啟網頁版更適合放進日常工作流程；但在中國地區使用時，最先遇到的往往不是命令本身，而是登入頁面打不開、API 請求逾時，以及終端機和瀏覽器代理設定不一致。

Gemini CLI 的連線大致可以分成兩部分。第一部分是登入或授權，可能需要開啟瀏覽器完成 Google 帳戶授權；第二部分是模型 API 通訊，也就是 CLI 在你輸入問題後，向遠端服務傳送請求並接收回應。瀏覽器能開啟登入頁，不代表終端機一定能連線；反過來，終端機設定了代理，也不代表瀏覽器已經使用同一個代理。

因此，排查時不要只看 v2rayN 主視窗中的「已連線」狀態。你需要分別確認節點、v2rayN 代理模式、瀏覽器授權，以及終端機環境變數是否形成完整鏈路。本文以 Windows 上的 v2rayN 為主要例子，macOS 與 Linux 的原理相同，只是開啟終端機代理的指令寫法略有不同。

使用前準備節點與 v2rayN

首先確認你已經取得合法、可信且仍然有效的節點或訂閱來源。v2rayN 本身只是本機代理用戶端，不會自動提供 Gemini 帳戶、API 金鑰或網路服務。若你只有訂閱連結，可以在 v2rayN 中新增訂閱並更新；若手上是單條分享連結，則按照對應協定匯入。常見分享格式包括 vmess://、vless://、trojan:// 與 ss://，不要把單節點連結誤填到訂閱地址欄位。

匯入完成後，先選擇一個延遲較低、最近使用時較穩定的節點。不要一開始就同時開啟多個代理工具，也不要在 v2rayN、瀏覽器外掛和系統 VPN 之間疊加代理。多層代理可能造成 DNS、路由和連接埠互相干擾，最後很難判斷究竟是哪一層出了問題。

第一次設定 Gemini CLI，建議先使用 v2rayN 的系統代理模式，而不是立即開啟 TUN。系統代理的範圍比較容易理解，也方便確認瀏覽器和一般 HTTP 請求是否真的經過 v2rayN。只有在終端機或特定應用明確不遵循系統代理時，才需要進一步設定環境變數或考慮 TUN。模式越複雜，排錯時需要同時檢查的項目就越多。

在 v2rayN 中開啟系統代理後，先用瀏覽器測試一般網站，再開啟 Gemini 的登入或開發者頁面。若瀏覽器連線不穩定，先處理節點和代理問題，不要急著安裝或重裝 Gemini CLI。只有當瀏覽器已經穩定、v2rayN 日誌也沒有大量連線錯誤時，才適合進入終端機設定階段。

動手設定終端機代理

終端機是否走代理，不能只看 Windows 的系統代理開關。不同命令列工具可能讀取不同的設定：有些會讀取 HTTP_PROXY 和 HTTPS_PROXY，有些會讀取 ALL_PROXY，也有些工具完全不理會系統代理。因此，最穩妥的做法是先確認 v2rayN 的本機 HTTP 或 SOCKS 監聽連接埠，再在目前終端機工作階段中明確指定代理。

在 v2rayN 的設定或主介面中，查看本機 HTTP 代理連接埠。常見值可能是 10809、10808 或其他自訂連接埠，實際數字必須以你的 v2rayN 畫面為準，不要直接照抄別人的設定。假設本機 HTTP 代理是 127.0.0.1:10809，Windows PowerShell 可以在目前視窗輸入 $env:HTTP_PROXY="http://127.0.0.1:10809" 和 $env:HTTPS_PROXY="http://127.0.0.1:10809"。這兩個變數只對目前 PowerShell 視窗及其後啟動的程式有效。

如果你使用 Windows 命令提示字元，可以設定 set HTTP_PROXY=http://127.0.0.1:10809 與 set HTTPS_PROXY=http://127.0.0.1:10809。macOS 或 Linux 的常見寫法則是 export HTTP_PROXY=http://127.0.0.1:10809 與 export HTTPS_PROXY=http://127.0.0.1:10809。注意：這些指令只是在目前終端機程序中加入代理變數，關閉視窗後通常不會永久保留。

若你的 v2rayN 只提供 SOCKS 代理，可依工具支援情況使用 ALL_PROXY=socks5://127.0.0.1:連接埠。不要把 SOCKS 連接埠當成 HTTP 連接埠使用，協定寫法和實際監聽類型必須一致。部分程式支援 socks5h，它會把網域解析也交給代理端；若遇到 DNS 解析異常，可以查閱該工具的支援方式，再決定是否使用。

設定完成後，先不要直接判斷 Gemini CLI 是否成功。可以先用一個簡單的網路請求工具測試，例如確認命令列能否取得一個你平時可存取的 HTTPS 網頁。測試的目的不是測量速度，而是確認「目前終端機」確實能透過指定的本機代理建立 TLS 連線。若測試失敗，優先檢查 v2rayN 是否仍在執行、連接埠是否填對，以及環境變數是否在同一個終端機視窗中生效。

登入與 API 使用方式

Gemini CLI 的授權方式可能隨版本和官方政策調整，常見流程包括瀏覽器登入授權，或使用 Gemini API 金鑰。請以你目前安裝版本的官方說明和終端機提示為準，不要把網路上針對舊版本的指令當成永久不變的標準。若登入流程要求瀏覽器確認，先確保瀏覽器使用的代理與 v2rayN 系統代理一致，再回到終端機完成授權。

使用瀏覽器授權時，終端機可能會列出一個網址，或嘗試自動開啟瀏覽器。若瀏覽器頁面一直載入，先檢查瀏覽器是否被設定成直連、是否存在另一個代理外掛，以及系統日期和時區是否正確。TLS 憑證驗證對時間很敏感，時間偏差過大時，登入頁和 API 都可能出現看似不相關的錯誤。

若使用 API 金鑰，請把金鑰視為敏感憑證，不要直接貼到公開聊天、Git 儲存庫、截圖或專案檔案中。可以依照 Gemini CLI 版本要求使用環境變數或其設定檔，但要確認設定檔權限和版本格式。若你在團隊電腦上工作，尤其不要把金鑰寫進會被提交到版本控制的 .env、Shell 腳本或自動化工作流程。

中國地區使用者還要注意服務可用性、帳戶資格、API 配額和付款政策等因素。代理只能改善本機到服務端的網路路徑，不能解決帳戶沒有權限、配額用完、金鑰失效或服務政策限制。若錯誤訊息明確指向授權、配額或帳戶狀態，就應該到官方帳戶頁面確認，而不是不斷更換節點。

v2rayN 分流與連線策略

讓 Gemini CLI 使用代理，並不代表所有本機流量都必須經過代理。v2rayN 的分流規則可以把不同網域或流量類型分配到代理、直連或阻斷，但規則名稱與介面會因版本、核心和設定檔而不同。新手先使用能正常工作的基本模式，等 Gemini CLI 完成登入和請求驗證後，再逐步細化規則，會比一開始建立大量自訂規則更容易成功。

如果你的目標只是讓 Gemini CLI 工作，先確認與登入及 API 請求相關的官方網域能夠穩定透過代理。不要只把一個你猜測的網域加入規則，因為登入、重新導向、憑證檢查和 API 請求可能涉及不同的主機。遇到請求逾時時，可以查看 v2rayN 的連線日誌，觀察實際被請求的主機名稱，再根據日誌調整規則，而不是盲目加入一長串網域。

DNS 也是分流中常被忽略的一環。若網域解析在本地完成，但解析結果不可用，後續即使代理節點正常也可能連不上。若你發現瀏覽器偶爾可以開啟、終端機卻經常出現解析失敗，應檢查目前核心的 DNS 設定和路由模式。修改前先備份原有配置，並一次只調整一項，這樣才能知道哪個變更真正有效。

TUN 模式可以接管更多不遵循系統代理的流量，但會引入虛擬網卡、系統權限、路由衝突和其他 VPN 軟體相容性等新變數。對 Gemini CLI 而言，只有在明確確認環境變數和系統代理都沒有生效時，才值得測試 TUN。即使開啟 TUN，也要先關閉其他代理軟體，並確認終端機、瀏覽器和 v2rayN 日誌的結果彼此一致。

常見錯誤與排查順序

如果 Gemini CLI 顯示登入頁無法開啟，先測試瀏覽器代理，再確認目前終端機是否設定了正確的代理變數。如果瀏覽器正常而 CLI 逾時，通常應優先檢查終端機變數、代理協定和連接埠；如果兩者都失敗，則回到節點、v2rayN 系統代理和分流規則。不要在兩個層級同時修改，否則很快會失去可比較的基準。

如果出現 connection refused，通常代表本機指定的連接埠沒有程式監聽，或你填入了錯誤的 HTTP / SOCKS 連接埠。若出現逾時，可能是節點品質、路由規則、DNS 或服務端回應問題。若出現未授權、金鑰無效或配額不足，則屬於帳戶和 API 設定問題，與 v2rayN 是否連線成功是兩回事。

建議按照以下順序排查：

確認 v2rayN 正在執行，且選中的節點可以穩定連線。
確認系統代理已開啟，並用瀏覽器測試相關登入頁。
確認目前終端機中的 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 指向正確連接埠。
重新開啟一個終端機視窗，避免使用尚未更新環境變數的舊程序。
查看 v2rayN 日誌，確認請求是否到達代理核心，以及實際請求的主機名稱。
最後才檢查 CLI 版本、登入方式、API 金鑰、配額和帳戶權限。

完成測試後，如果不再需要讓所有命令列工具走代理，可以關閉目前工作階段的環境變數，或只在啟動 Gemini CLI 的腳本中設定。這樣能避免套件管理器、版本控制工具和其他不需要代理的命令意外使用同一條網路路徑，也能減少憑證、DNS 和速度問題。

穩定使用的實際建議

Gemini CLI 適合用來協助閱讀程式碼、解釋錯誤、整理檔案和產生初步方案，但輸出的內容仍需要人工審核。涉及刪除檔案、修改部署設定、執行資料庫操作或提交程式碼時，先閱讀差異內容，再決定是否接受。網路穩定只代表請求能正常完成，不代表每個命令列操作都安全。

日常使用時，可以為 Gemini CLI 建立一個獨立的終端機設定流程：啟動 v2rayN、選擇已驗證的節點、設定本機代理環境變數，完成工作後關閉或清除變數。若團隊成員需要共同使用，應把代理端點、金鑰管理和權限範圍分開說明，避免把個人節點或 API 憑證直接寫進共享腳本。

總結來說，v2rayN 連線設定的重點不是「一直換節點」，而是確認每一層都使用同一套邏輯：v2rayN 有可用節點，瀏覽器能完成授權，終端機明確指向本機代理，分流規則涵蓋實際請求的網域，最後再檢查帳戶和 API 權限。依照這個順序設定，Gemini CLI 在中國地區遇到的登入、逾時和連線不穩問題，通常會更容易定位。