---
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="/docs/gemini-cli/official/02-context-config/28-trusted-folders" />
  <Card title="Settings" description="主题最终要回到 settings.json 固化。" href="/docs/gemini-cli/official/02-context-config/20-settings" />
  <Card title="Local development" description="如果是录屏或教程环境，继续看本地开发配置。" href="/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)
