故障排查与参考

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
故障排查与参考	reference	排障和参考资料总览。
按现象定位	by symptom	从问题反查该看哪篇。
实时核验	live check	版本类信息以官方为准。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你按问题快速定位该看 Gemini CLI 的哪篇排障或参考。

你是 Gemini CLI 排障参考导航顾问。

【角色】
Gemini CLI 排障参考导航顾问，按分层定位、一次只改一个变量的原则帮我找根因，每条结论落到能照做的步骤。

【输入】
- 我的问题或需求：___
- 涉及方面（安装 / 故障 / 版本 / 包）：___
- 最近的变化：___
- 紧迫程度：___
- 经验水平：___

【工作流程】
1. 把需求归到对应类别
2. 指向该看的篇
3. 给分层排查起点
4. 提示需实时核验或找支持
5. 给落地下一步

【输出规范】
▌一、需求归类
▌二、对应篇
▌三、分层排查起点
▌四、核验 / 支持

【硬约束】
- 一次只改一个变量定位根因
- 版本类以官方为准
- 敏感信息不暴露
- 不要替我臆测原因或编造不存在的设置，信息不全先问清
- 不确定的机制或报错一律以官方文档为准，禁止照搬过时写法

这组页面负责把“遇到问题怎么判断”讲清楚。Gemini CLI 的常见问题通常集中在认证、配额、Node 环境、sandbox、CI 环境变量和版本渠道。

排障入口的目标是缩小范围：先判断问题属于账号、网络、安装、配置、权限、版本还是源码开发，再进入对应页面。

学习路径

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

FAQ

先排除配额、OAuth、ESM、cached token 和 API key 存储误解。

故障排查

按认证、证书、PATH、MCP、sandbox、CI 和退出码分层定位。

版本与包结构

更新、卸载、release notes 和 NPM package 边界集中处理。

页面	解决的问题
FAQ	常见误解、配额、ESM、缓存 token、API key 存储
故障排查	登录、证书、PATH、MCP、sandbox、CI、退出码
卸载	npx cache、npm global、Homebrew、MacPorts、配置残留
Release notes	stable / preview / nightly、版本变更和教程复检
NPM package	CLI/core 包边界、workspace、源码排查

排查顺序

先确认版本 -> 再看认证方式 -> 再看环境变量 -> 再看网络/证书 -> 最后看 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。

排障验收

一个排障结论至少要能说明：根因属于哪一层、用什么证据确认、改了什么、如何复现成功、是否影响其他入口。只写“重装后好了”不够，后续版本变化时无法复用。

如果问题和账号、配额、预览模型、release channel 或 npm package 有关，还要记录具体日期。Gemini CLI 迭代快，过期排障结论会误导后续教程和用户。

排障完成后，最好把对应页面的来源链接和验证日期一起更新。