---
title: "Token caching"
description: "Gemini CLI token caching 的作用：減少重複上下文成本、提升長任務效能，以及使用前需要理解的邊界。"
verifiedAt: "2026-05-09"
---

Token caching 用來減少重複上下文帶來的成本或延遲。它適合長會話、重複讀取大上下文、指令碼化任務。

> [!IMPORTANT]
> Token caching 受認證方式影響。API key 和 Vertex AI 場景可用；OAuth / Code Assist API 場景不要把 cached token 當成必然存在。

官方文件裡的限制很關鍵：token caching 只在 API key 認證或 Vertex AI 場景下可用。OAuth 使用者，包括 Google Personal / Enterprise 賬號走的 Code Assist API，目前不支援 cached content creation。

## 適合場景

- 多輪圍繞同一大專案。
- 反覆讀取同一批文件。
- CI/headless 中重複上下文。
- 長時間任務需要穩定效能。

## 它快取什麼

Token caching 的目標不是快取最終答案，而是複用前面已經處理過的系統指令和上下文。這樣後續請求不需要重複為同樣上下文付完整處理成本。

官方頁面沒有給出統一 TTL 或永久快取承諾，所以教程裡不要寫“快取會保留多久”。更穩的寫法是教讀者看 `/stats`，確認當前認證方式下是否真的出現 cached token。

適合快取的內容通常是：

- 穩定系統指令。
- 專案規則。
- 長期不變的上下文。
- 多輪任務反覆引用的檔案摘要。

不適合依賴 caching 的內容包括即時日誌、臨時錯誤輸出、頻繁變化的 diff 和一次性輸入。

| 內容 | 是否適合 caching | 原因 |
| --- | --- | --- |
| 專案規則 / system instructions | 適合 | 穩定且重複出現 |
| 長文件和 schema | 適合 | 多輪任務會重複引用 |
| 當前 diff | 不適合 | 變化快，容易誤用舊上下文 |
| 測試失敗日誌 | 不適合 | 每次執行都可能不同 |
| 構建產物和依賴目錄 | 不適合 | 應先 ignore 或裁剪 |

## 不適合把它當萬能解法

如果任務描述混亂、專案規則缺失、驗證命令不清楚，token caching 也救不了。先把上下文結構和任務邊界做好。

也不要把 caching 理解成“所有 token 都免費”。它只是減少重複處理成本，不能替代上下文裁剪。

## 如何檢視效果

在 Gemini CLI 會話裡使用 `/stats` 檢視 token usage。當 cached token 可用時，stats 輸出裡會顯示相關節省情況。

如果 `/stats` 看不到 cached token，先確認當前認證方式是不是 Gemini API key 或 Vertex AI。如果你是 OAuth 登入，缺少 cached token 資訊是預期行為。

這也是為什麼團隊覆盤成本時要記錄認證方式。

如果團隊成員分別使用 OAuth、API key 和 Vertex AI，同一篇教程裡的 caching 截圖可能完全不同。商業教程建議把認證方式寫在截圖說明裡，否則讀者會以為自己配置錯了。

## 成本最佳化建議

- 用 `.geminiignore` 排除構建產物、依賴目錄、日誌和大檔案。
- 自動化任務要記錄 `/stats`，否則很難判斷成本變化來自快取、模型切換還是上下文變化。
- 先減少無關上下文，再考慮 token caching。
- 團隊場景要統一認證方式，否則不同成員看到的 caching 行為可能不同。

## 驗證步驟

先準備一個穩定的大上下文任務，例如讀取同一組 docs 或 schema。第一輪執行後看 `/stats`，第二輪用同一認證方式、同一模型和同一上下文再執行一次，再比較 cached token 是否出現。中間不要改 `GEMINI.md`、settings、模型或輸入檔案，否則你無法判斷變化來自快取還是輸入漂移。

如果第二輪仍看不到 cached token，不要繼續改 prompt。先確認認證方式、官方支援範圍、模型是否支援 cached content creation，再判斷是否需要改成本最佳化策略。

## 接下來去哪

<Cards>
  <Card title="ACP mode" description="繼續看 IDE / 工具鏈透過協議控制 Gemini CLI 的執行方式。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime/55-acp-mode" />
  <Card title=".geminiignore" description="快取前先裁剪不該進入上下文的檔案。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/23-gemini-ignore" />
  <Card title="Quota and pricing" description="成本最佳化要和 quota、模型選擇、認證方式一起看。" href="/zh-Hant/docs/gemini-cli/official/00-getting-started/06-quota-and-pricing" />
</Cards>

## 官方來源

- [Gemini CLI token caching](https://google-gemini.github.io/gemini-cli/docs/cli/token-caching.html)
- [Gemini CLI token caching source](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/token-caching.md)
- [Gemini CLI core](https://google-gemini.github.io/gemini-cli/docs/core/)
