---
title: "故障排查與參考"
description: "Gemini CLI 故障排查與參考入口：FAQ、登入錯誤、常見報錯、解除安裝、release notes 和 npm package 結構。"
verifiedAt: "2026-05-09"
---

這組頁面負責把“遇到問題怎麼判斷”講清楚。Gemini CLI 的常見問題通常集中在認證、配額、Node 環境、sandbox、CI 環境變數和版本渠道。

> [!NOTE]
> 排障入口的目標是縮小範圍：先判斷問題屬於賬號、網路、安裝、配置、許可權、版本還是原始碼開發，再進入對應頁面。

## 學習路徑

```mermaid
flowchart LR
    FAQ["FAQ"] --> Troubleshooting["Troubleshooting"]
    Troubleshooting --> Uninstall["Uninstall"]
    Troubleshooting --> Release["Release notes"]
    Release --> NPM["NPM package"]
    NPM --> Understanding["Understanding series"]

    style FAQ fill:#dbeafe,stroke:#3b82f6
    style Troubleshooting fill:#fee2e2,stroke:#ef4444
    style NPM fill:#dcfce7,stroke:#22c55e
```

<Cards>
  <Card title="FAQ" description="先排除配額、OAuth、ESM、cached token 和 API key 儲存誤解。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/80-faq" />
  <Card title="故障排查" description="按認證、證書、PATH、MCP、sandbox、CI 和退出碼分層定位。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting" />
  <Card title="版本與包結構" description="更新、解除安裝、release notes 和 NPM package 邊界集中處理。" href="/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/83-release-notes" />
</Cards>

## 目錄

| 頁面 | 解決的問題 |
| --- | --- |
| [FAQ](/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/80-faq) | 常見誤解、配額、ESM、快取 token、API key 儲存 |
| [故障排查](/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting) | 登入、證書、PATH、MCP、sandbox、CI、退出碼 |
| [解除安裝](/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/82-uninstall) | npx cache、npm global、Homebrew、MacPorts、配置殘留 |
| [Release notes](/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/83-release-notes) | stable / preview / nightly、版本變更和教程複檢 |
| [NPM package](/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/84-npm-package) | CLI/core 包邊界、workspace、原始碼排查 |

## 排查順序

```text
先确认版本 -> 再看认证方式 -> 再看环境变量 -> 再看网络/证书 -> 最后看 sandbox 和工具权限
```

排障時不要先改配置。先把錯誤原文、CLI 版本、安裝來源、認證方式、當前目錄、是否 sandbox、是否 CI 記錄下來。很多問題看起來像模型失敗，實際是 PATH、證書、配額或環境變數。

## 分流判斷

| 你看到的現象 | 優先進入 |
| --- | --- |
| 429、OAuth、cached token、API key | FAQ |
| 登入失敗、證書失敗、command not found | 故障排查 |
| 舊版本、安裝來源混亂、npx 快取 | 解除安裝 |
| preview/nightly 行為變化 | Release notes |
| stack trace 進入 `packages/core` | NPM package |

## 下一步

先讀：[FAQ](/zh-Hant/docs/gemini-cli/official/08-troubleshooting-reference/80-faq)。

## 排障驗收

一個排障結論至少要能說明：根因屬於哪一層、用什麼證據確認、改了什麼、如何復現成功、是否影響其他入口。只寫“重灌後好了”不夠，後續版本變化時無法複用。

如果問題和賬號、配額、預覽模型、release channel 或 npm package 有關，還要記錄具體日期。Gemini CLI 迭代快，過期排障結論會誤導後續教程和使用者。

排障完成後，最好把對應頁面的來源連結和驗證日期一起更新。

## 官方來源

- [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)
