---
title: "Themes"
description: "Gemini CLI themes 的用途：終端 UI 個性化、可讀性和團隊教程截圖一致性。"
verifiedAt: "2026-05-09"
---

Themes 影響 Gemini CLI 的終端顯示。它不是核心能力，但會影響長時間使用的可讀性。

> [!NOTE]
> 主題配置的目標是可讀和一致，不是把教程截圖做得花哨。終端工具最重要的是文本、diff、warning 和 error 都能看清。

可以透過 `/theme` 互動選擇，也可以在 `settings.json` 的 `ui.theme` 或 `ui.customThemes` 固定。官方內建深色和淺色主題，也支援 extension 提供主題。

## 什麼時候需要配置主題

- 深色/淺色終端不匹配。
- 錄屏或截圖需要統一風格。
- 字型顏色在當前終端裡不清晰。
- 團隊教程要保持截圖一致。

## 配置方式

互動方式：

```text
/theme
```

如果 `settings.json` 裡已經固定了 `ui.theme`，需要先移除該配置，否則 `/theme` 中的互動選擇可能不會覆蓋檔案裡的配置。

自定義主題放在 `ui.customThemes`，至少要定義 `name`、`type: "custom"`、背景色和主要文字色。也可以把主題放在獨立 JSON 檔案裡，再在 `ui.theme` 指向該檔案路徑。出於安全考慮，Gemini CLI 只會載入位於使用者 home 目錄內的主題檔案。

官方主題變數不只影響普通文字。常見變數包括 `Background`、`Foreground`、`AccentBlue`、`AccentPurple`、`AccentCyan`、`AccentGreen`、`AccentYellow`、`AccentRed`、`Comment`、`Gray`，以及用於 diff 的 `DiffAdded`、`DiffRemoved`、`DiffModified`。如果主題沒有覆蓋關鍵狀態色，程式碼修改和錯誤提示會很難讀。

一個穩定的教程主題至少要檢查三類畫面：普通對話、工具確認、diff 展示。只看歡迎頁好不好看沒有意義，真正影響學習體驗的是 warning、error、added、removed 這些狀態是否清晰。

## 教程截圖建議

教程站不要追求花哨主題，優先選對比度穩定、淺深色都可讀的主題。截圖前固定主題、終端字型和視窗寬度，否則同一篇教程裡 UI 變化會顯得不專業。

| 場景 | 推薦做法 | 避免 |
| --- | --- | --- |
| 教程截圖 | 固定主題、字型、視窗寬度 | 每張圖隨機主題 |
| 長時間編碼 | 選擇對比度穩定的主題 | 低對比度彩色主題 |
| 團隊文件 | 用專案文件記錄截圖環境 | 只靠個人終端偏好 |
| 自定義主題 | 先檢查 warning、error、diff 色 | 只看普通文本 |

如果教程面向新手，主題更應該接近預設體驗。過度自定義會讓讀者開啟自己的終端後找不到對應 UI 狀態。

## 不要過度投入

主題不會提升 agent 質量。先把上下文、許可權、工具、驗證流程做好，再調視覺。

如果主題只是個人偏好，放使用者級 settings；只有教程錄屏、團隊截圖規範或共享開發環境需要一致時，才考慮寫入專案文件。不要因為自己喜歡某個顏色，就把 `ui.theme` 固定進儲存庫級配置。

## 常見排錯

主題不生效時，先看 `settings.json` 裡是否已經固定 `ui.theme`。如果檔案裡寫死了主題，`/theme` 的互動選擇可能不會覆蓋這個配置。第二步檢查自定義主題檔案是否在 home 目錄內；官方出於安全原因不會從任意路徑載入主題 JSON。

顏色看不清時，不要只調背景色。優先檢查 `Foreground`、`Comment`、`AccentRed`、`AccentYellow` 和 diff 相關變數。warning、error、diff 刪除行是教程截圖裡最容易出問題的地方。

## 截圖驗收清單

教程站截圖要固定三件事：終端寬度、字型大小、主題名稱。每次換主題後，至少截一張普通對話、一張命令確認、一張檔案 diff。三張都清楚，才說明主題適合教學內容。

如果頁面要給讀者複製配置，建議同時說明這是視覺配置，不影響模型能力、配額、上下文和工具許可權。新手最容易把 UI 變化誤解成“模型模式變化”，這一點要在教程裡主動消除。

主題只服務可讀性，不應承擔功能解釋，也不應掩蓋真實命令輸出和錯誤資訊。

## 驗收方式

執行 `/theme` 確認可選列表裡出現預期主題。自定義主題要同時檢查普通文本、程式碼塊、diff added/removed、warning/error 狀態色，確保錄屏和截圖中不會看不清。

## 接下來去哪

<Cards>
  <Card title="Trusted folders" description="UI 配置結束後，繼續看 workspace 信任和安全邊界。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/28-trusted-folders" />
  <Card title="Settings" description="主題最終要回到 settings.json 固化。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/20-settings" />
  <Card title="Local development" description="如果是錄屏或教程環境，繼續看本地開發配置。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/76-local-development" />
</Cards>

## 官方來源

- [Gemini CLI themes](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/themes.md)
