故障排查与参考

这组页面负责把“遇到问题怎么判断”讲清楚。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 迭代快，过期排障结论会误导后续教程和用户。

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