故障排查
Gemini CLI 常見故障排查：認證錯誤、地區限制、證書、PATH、MCP 埠、sandbox 許可權、CI 環境和退出碼。
排查 Gemini CLI 不要先重灌。先按錯誤型別定位：認證、網路、安裝、配置、sandbox、CI。
排障順序要從“當前命中了哪個 gemini、用了什麼認證、讀了哪些配置”開始。直接重灌往往會保留舊配置，反而看不出根因。
排查總覽
| 錯誤型別 | 第一檢查項 | 常見根因 |
|---|---|---|
| 登入失敗 | 賬號型別、GOOGLE_CLOUD_PROJECT、認證方式 | Workspace / Cloud 賬號 entitlement 或專案變數不匹配 |
| 證書錯誤 | 企業代理、Node CA 配置 | TLS inspection 沒有把公司根證書交給 Node |
| command not found | command -v gemini、npm global bin、PATH | 安裝來源和 shell PATH 不一致 |
| import / module 錯誤 | 依賴、build、原始碼入口 | 原始碼環境未安裝或未構建 |
| sandbox 拒絕 | 寫入路徑、被呼叫命令、sandbox 型別 | 試圖訪問專案外或受限路徑 |
| CI 不互動 | CI / CONTINUOUS_INTEGRATION / CI_* 環境變數 | TUI 被判定為非互動環境 |
認證錯誤
如果看到 Gemini Code Assist Standard subscription 相關錯誤，先檢查：
先用 echo $GOOGLE_CLOUD_PROJECT 和 echo $GOOGLE_CLOUD_PROJECT_ID 檢查環境變數。
個人賬號誤設定這些變數，可能觸發組織訂閱檢查。個人使用者可以先 unset；組織使用者需要管理員分配 entitlement。
地區不可用
如果登入提示當前賬號所在地區不可用，需要查 Gemini Code Assist 支援地區。這個問題不是本地配置能修復的。
證書錯誤
企業網路或代理可能攔截 TLS，導致：
典型報錯包括 UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 unable to get local issuer certificate。
官方 troubleshooting 的直接做法是把企業根證書交給 Node：
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt如果公司網路要求統一代理，還要同時檢查 shell、npm、Node 和 Gemini CLI 執行環境是否都走同一代理。不要把證書錯誤誤判成 Gemini 賬號錯誤。
gemini command not found
檢查安裝方式和 PATH：
先看全域性包、npm prefix 和 PATH：npm list -g @google/gemini-cli、npm config get prefix、echo $PATH。
如果是全域性安裝，更新命令是：
全域性安裝的更新命令是 npm install -g @google/gemini-cli@latest。
如果是原始碼執行，要確認使用的是原始碼入口，並且已經重新 build。普通使用者教程不應預設走原始碼入口。
MODULE_NOT_FOUND 或 import 錯誤
這類錯誤通常發生在原始碼開發或依賴損壞場景。先按官方建議恢復最小鏈路：
npm install
npm run build
npm run start如果你只是普通使用者，不要在業務專案裡反覆改 package.json 來修 Gemini CLI；先用全域性安裝或 npx @google/gemini-cli 在空目錄復現。
MCP 埠占用
EADDRINUSE 表示 MCP server 要繫結的埠已被佔用。處理方式是停止佔用程序，或給 MCP server 換埠。
Sandbox 許可權錯誤
Operation not permitted 或 Permission denied 在 sandbox 下常見。先判斷 Gemini CLI 是否試圖寫專案外路徑、系統臨時目錄以外路徑，或呼叫被限制的命令。
CI 環境不進互動模式
如果環境變數裡存在 CI、CONTINUOUS_INTEGRATION 或 CI_ 字首變數，CLI 可能判斷為非互動環境。
臨時規避：
臨時規避可以用 env -u CI_TOKEN gemini。
DEBUG 不從專案 .env 生效
官方 troubleshooting 提到，專案 .env 裡的 DEBUG 和 DEBUG_MODE 會被自動排除，避免干擾 Gemini CLI 行為。要開啟 debug，優先使用 .gemini/.env，或明確調整 settings.json 裡的 advanced.excludedEnvVars。
退出碼
常見退出碼：41 是認證錯誤，42 是輸入錯誤，44 是 sandbox 錯誤，52 是配置錯誤，53 是 turn limit 錯誤。
| 退出碼 | 含義 | 排查入口 |
|---|---|---|
41 | 認證錯誤 | 登入方式、賬號、project、API key |
42 | 輸入錯誤 | headless 引數、stdin、非互動輸入 |
44 | sandbox 錯誤 | Docker / Podman / Seatbelt、寫入路徑 |
52 | 配置錯誤 | 全域性和專案 settings.json |
53 | turn limit | 任務拆分、上下文、自動化迴圈 |
最小復現
排障記錄要能復跑：
- 在空目錄執行同一命令。
- 記錄
gemini --version和command -v gemini。 - 標註認證方式，不貼 token。
- 臨時移開專案
.gemini/後複測。 - 如果涉及 MCP、hooks 或 shell，單獨驗證底層命令是否可執行。