故障排查與參考

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
故障排查與參考	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 迭代快，過期排障結論會誤導後續教學和使用者。

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