故障排查與參考

這組頁面負責把“遇到問題怎麼判斷”講清楚。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 迭代快，過期排障結論會誤導後續教程和使用者。

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