---
title: "故障排查"
description: "Gemini CLI 常見故障排查：認證錯誤、地區限制、證書、PATH、MCP 埠、sandbox 許可權、CI 環境和退出碼。"
verifiedAt: "2026-05-09"
---

排查 Gemini CLI 不要先重灌。先按錯誤型別定位：認證、網路、安裝、配置、sandbox、CI。

> [!IMPORTANT]
> 排障順序要從“當前命中了哪個 `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：

```bash
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 錯誤

這類錯誤通常發生在原始碼開發或依賴損壞場景。先按官方建議恢復最小鏈路：

```bash
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 | 任務拆分、上下文、自動化迴圈 |

## 最小復現

排障記錄要能復跑：

1. 在空目錄執行同一命令。
2. 記錄 `gemini --version` 和 `command -v gemini`。
3. 標註認證方式，不貼 token。
4. 臨時移開專案 `.gemini/` 後複測。
5. 如果涉及 MCP、hooks 或 shell，單獨驗證底層命令是否可執行。

## 下一步

<Cards>
  <Card title="解除安裝" description="確認是安裝包或快取問題後，再按安裝來源解除安裝。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/82-uninstall" />
  <Card title="Sandbox" description="許可權錯誤和隔離問題回到 sandbox 頁面。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title="MCP setup" description="MCP 埠、啟動和配置問題回到 MCP setup。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
</Cards>

## 官方來源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
- [Gemini CLI troubleshooting guide](https://google-gemini.github.io/gemini-cli/docs/troubleshooting.html)
