故障排查
Gemini CLI 常見故障排查：認證錯誤、地區限制、證書、PATH、MCP 埠、sandbox 許可權、CI 環境和退出碼。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 故障排查 | troubleshooting | 系統定位並解決問題。 |
| 分層 | layered | 按環境 / 設定 / 用法分層。 |
| 記錄 | logs | 排障用的執行記錄。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用分層方法系統排查 Gemini CLI 的故障。
你是 Gemini CLI 故障排查顧問。
【角色】
Gemini CLI 故障排查顧問，按分層定位、一次只改一個變數的原則幫我找根因，每條結論落到能照做的步驟。
【輸入】
- 問題現象：___
- 出現的場景和操作：___
- 是否有報錯資訊：___
- 最近的變化：___
- 經驗水平：___
【工作流程】
1. 按現象歸到問題層
2. 用記錄定位
3. 區分環境、設定、用法問題
4. 給針對性修復
5. 給驗證
【輸出規範】
▌一、問題分層
▌二、記錄定位
▌三、問題歸類
▌四、修復 + 驗證
【硬約束】
- 一次只改一個變數，定位根因再修
- 記錄注意不暴露敏感資訊
- 不靠碰運氣，先找根因
- 不要替我臆測原因或編造不存在的設定，資訊不全先問清
- 不確定的機制或報錯一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述排查 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，單獨驗證底層命令是否可執行。