---
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="/docs/gemini-cli/official/08-troubleshooting-reference/80-faq" />
  <Card title="故障排查" description="按认证、证书、PATH、MCP、sandbox、CI 和退出码分层定位。" href="/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting" />
  <Card title="版本与包结构" description="更新、卸载、release notes 和 NPM package 边界集中处理。" href="/docs/gemini-cli/official/08-troubleshooting-reference/83-release-notes" />
</Cards>

## 目录

| 页面 | 解决的问题 |
| --- | --- |
| [FAQ](/docs/gemini-cli/official/08-troubleshooting-reference/80-faq) | 常见误解、配额、ESM、缓存 token、API key 存储 |
| [故障排查](/docs/gemini-cli/official/08-troubleshooting-reference/81-troubleshooting) | 登录、证书、PATH、MCP、sandbox、CI、退出码 |
| [卸载](/docs/gemini-cli/official/08-troubleshooting-reference/82-uninstall) | npx cache、npm global、Homebrew、MacPorts、配置残留 |
| [Release notes](/docs/gemini-cli/official/08-troubleshooting-reference/83-release-notes) | stable / preview / nightly、版本变更和教程复检 |
| [NPM package](/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](/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)
