---
title: "切換主題"
description: "選擇內建主題，或用少量顏色定義自己的 OpenCode TUI 主題。"
verifiedAt: "2026-05-09"
---

主題隻影響閱讀體驗，不影響模型能力。新手優先從內建主題開始，不要一上來複制一份幾百行配色表。

> [!NOTE]
> **這一篇用 6 分鐘換什麼**：你會知道主題該解決什麼問題、先試哪些內建主題、主題檔案放哪裡，以及怎麼用最少配置改善 TUI 可讀性。

## 先給結論：主題先解決可讀性

主題配置解決的是長時間閱讀、選單定位和 diff 對比時的可讀性問題。不要把主題當裝飾，真正要檢查的是正文、選中項、diff、新增刪除和錯誤提示。

正確順序是：

1. 先選一個內建主題。
2. 確認終端支援真彩色。
3. 只在確實讀不清時自定義少數顏色。
4. 最後才考慮完整主題。

```mermaid
flowchart LR
  BuiltIn["內建主題"] --> Terminal["確認終端真彩色"]
  Terminal --> Check["真實會話檢查 diff / 選單 / 錯誤狀態"]
  Check --> Minimal["少量自定義顏色"]
  Minimal --> Full["必要時再做完整主題"]

  style BuiltIn fill:#dbeafe,stroke:#3b82f6
  style Check fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Full fill:#fef3c7,stroke:#f59e0b
```

## 先選內建主題

OpenCode 內建多種主題，例如 `system`、`tokyonight`、`everforest`、`ayu`、`catppuccin`、`catppuccin-macchiato`、`gruvbox`、`kanagawa`、`nord`、`matrix`、`one-dark`，並且官方在持續新增。可以在 TUI 裡用 `/theme` 命令現場切換試看。

建議先試三個：

- `system`：跟隨終端背景，適合已經精調過終端配色的人。
- `tokyonight`：暗色終端常用，層次比較清晰。
- `catppuccin`：對比度溫和，適合長時間閱讀。

在 `tui.json` 中指定主題：

```jsonc title="tui.json"
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}
```

## 终端先支持真彩色

如果主题颜色看起来发灰或不准，先检查终端是否支持真彩色：

```bash
echo $COLORTERM
```

输出最好是 `truecolor` 或 `24bit`。多数现代终端默认支持；如果没有，可以在 shell 配置里设置 `COLORTERM=truecolor`。

## 自定义主题放哪里

自定义主题是 JSON 文件。OpenCode 会从这些位置加载：

| 位置 | 适合场景 |
| --- | --- |
| `~/.config/opencode/themes/*.json` | 个人长期偏好 |
| `<project-root>/.opencode/themes/*.json` | 项目统一视觉风格 |
| `./.opencode/themes/*.json` | 当前工作目录临时主题 |

同名主题会被更高优先级的目录覆盖。个人偏好放用户级；团队统一视觉风格才放项目级。

## 最小自定义主题

自定义主题不需要从完整配色表开始。先定义基础颜色，确认读写舒服，再逐步细化语法高亮和 diff 颜色。

```jsonc title="~/.config/opencode/themes/my-theme.json"
{
  "$schema": "https://opencode.ai/theme.json",
  "theme": {
    "primary": "#88C0D0",
    "accent": "#A3BE8C",
    "error": "#BF616A",
    "text": "none",
    "background": "none",
    "backgroundPanel": "#2E3440",
    "border": "#4C566A"
  }
}
```

`"none"` 表示继承终端默认前景色或背景色。它适合想让 OpenCode 和终端整体外观保持一致的场景。

## 创建和启用主题

用户级主题：

```bash
mkdir -p ~/.config/opencode/themes
vim ~/.config/opencode/themes/my-theme.json
```

项目级主题：

```bash
mkdir -p .opencode/themes
vim .opencode/themes/my-theme.json
```

建立後，在 `tui.json` 中把 `theme` 設定為檔名對應的主題名。

## 怎麼判斷主題可用

切換主題後，用一個真實會話檢查：

- 普通回答是否能連續閱讀十分鐘不累。
- 程式碼塊和正文是否有明顯區分。
- diff 新增和刪除是否不用猜。
- 當前選中的選單項是否足夠醒目。
- 錯誤、警告、成功狀態是否能一眼分辨。

如果這些都沒問題，就不需要繼續調色。主題配置的目標是降低閱讀負擔，不是追求配置完整。

## 接下來去哪

<Cards>
  <Card title="TUI 工作流" description="主題、滑鼠、diff 樣式和命令面板都屬於 TUI 使用體驗。" href="/zh-Hant/docs/opencode/official/00-getting-started/tui" />
  <Card title="快捷鍵" description="視覺調順以後，再處理 leader key 和高頻快捷鍵衝突。" href="/zh-Hant/docs/opencode/official/01-customization/keybinds" />
  <Card title="配置 OpenCode" description="理解 `tui.json` 和 `opencode.json` 的職責邊界。" href="/zh-Hant/docs/opencode/official/01-customization/config" />
  <Card title="終端 TUI 工作流" description="從日常任務角度理解 OpenCode TUI 裡的高頻控制點。" href="/zh-Hant/docs/opencode/understanding/03-terminal-workflow" />
</Cards>

## 官方資料

- OpenCode Themes：[https://opencode.ai/docs/themes](https://opencode.ai/docs/themes)
- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
