一、问题背景
最近在 macOS 上使用 cmux 时，遇到了一个 Ghostty 主题加载错误。
cmux 是一款基于 Ghostty 终端渲染引擎构建的 macOS 终端应用，支持多工作区、分屏、垂直标签页和通知面板，非常适合同时运行多个 CLI 工具及 AI Coding Agent。
本次使用的版本信息如下：
| 项目 | 版本 |
|---|---|
| 应用 | cmux |
| Version | 0.65.1 |
| Build | 110 |
| Commit | 8a853dcc9 |
| 操作系统 | macOS |
| 终端引擎 | libghostty |
该版本于 2026 年 10 月 12 日发布。
官方发布记录：cmux v0.65.1。
启动 cmux 后，应用弹出了以下警告：
Ghostty 配置错误
theme "One Dark" not found,
tried path "/Users/zning/.config/ghostty/themes/One Dark"
theme "One Dark" not found,
tried path "/Applications/cmux.app/Contents/Resources/ghostty/themes/One Dark"
提示还表示，修正配置并保存后，cmux 会自动重新加载。
虽然终端仍然可以使用，但每次出现配置错误提示显然不太理想。
最初怀疑是升级到 cmux 0.65.1 后，Ghostty 的主题资源发生了变化，或者新版本存在主题打包问题。
经过排查，问题在检查主题名称和配置文件的阶段就得到了解决，无需重新安装 cmux。
二、理解 cmux 与 Ghostty 的配置关系
排查之前，需要先理解 cmux 的终端渲染架构。
cmux 使用 libghostty 作为终端渲染引擎，因此它可以使用 Ghostty 的大部分终端配置，包括：
- 终端主题和配色方案
- 字体、字号和字形设置
- 光标样式
- 背景透明度和模糊效果
- 终端内边距和自定义 Shader
不过，cmux 也拥有自己的应用配置体系。
根据 cmux 官方配置文档，主要涉及以下路径：
| 配置路径 | 用途 |
|---|---|
~/.config/ghostty/config |
Ghostty 共享配置 |
~/.config/ghostty/config.ghostty |
Ghostty 共享配置 |
~/Library/Application Support/com.mitchellh.ghostty/config.ghostty |
Ghostty macOS 配置 |
~/Library/Application Support/com.cmuxterm.app/config.ghostty |
cmux 专属 Ghostty 配置 |
~/.config/cmux/cmux.json |
cmux 应用界面、工作区及行为配置 |
其中有一个重要机制：
cmux 会在加载 Ghostty 共享配置后，再加载自己的 config.ghostty，因此后者的同名配置具有更高优先级。
例如：
# ~/.config/ghostty/config
theme = Catppuccin Mocha
如果同时存在：
# ~/Library/Application Support/com.cmuxterm.app/config.ghostty
theme = Atom One Dark
那么最终生效的主题配置会以 cmux 专属配置为准。
需要注意的是，即使后续配置覆盖了之前的设置，之前文件中的无效配置仍可能产生解析警告。
官方文档对此有明确说明。
三、问题原因：One Dark 主题名称不匹配
根据报错：
theme "One Dark" not found
可以确定，Ghostty 在加载配置时尝试解析名为 One Dark 的主题，但没有在指定路径找到对应文件。
Ghostty 支持通过主题名称引用内置主题：
theme = Catppuccin Mocha
也支持引用自定义主题。
如果按照名称引用，Ghostty 会在预定义的主题目录中寻找匹配文件。主题文件名称必须与所配置的名称一致。
这与 VS Code、JetBrains IDE 中通过插件名称或显示名称选择主题的机制有所不同。
Ghostty 不会自动将 One Dark 解析为其他名称相近的主题。
而在 Ghostty 的主题资源中，存在一个名称非常接近的主题：
Atom One Dark
其主题文件可以在这里查看：
Atom One Dark — iTerm2 Color Schemes
它包含完整的终端 ANSI Palette、背景色、前景色以及光标颜色。
例如：
background = #21252b
foreground = #abb2bf
cursor-color = #abb2bf
cursor-text = #21252b
因此，对于希望继续使用经典 One Dark 配色的用户，Atom One Dark 是值得优先检查的替代主题。
当然，是否可用仍应以本机实际安装的主题列表为准。
Ghostty 官方也提供了主题名称与自定义主题文件的详细说明：Ghostty Color Theme。
四、实际排查与修复步骤
整个排查过程相对简单。
Step 1：检查 cmux 内置主题
首先确认 cmux 当前能够识别哪些主题。
cmux themes list | grep -i "One Dark"
cmux themes list 是 cmux 官方支持的 CLI 命令，用于列出可用主题。
如果输出中包含：
Atom One Dark
则说明该主题已经可以被 cmux 识别。
也可以直接进入交互式主题选择器：
cmux themes
通过预览选择需要的主题。
从排障角度看，CLI 查询更直接，因为它可以快速检查所需主题名称是否存在。
Step 2：检查 Ghostty 配置中的主题引用
接下来定位哪个配置文件引用了错误的主题名称。
可以执行：
grep -HnE '^[[:space:]]*theme[[:space:]]*=' \
"$HOME/.config/ghostty/config" \
"$HOME/.config/ghostty/config.ghostty" \
"$HOME/Library/Application Support/com.mitchellh.ghostty/config" \
"$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty" \
"$HOME/Library/Application Support/com.cmuxterm.app/config.ghostty" \
2>/dev/null
这条命令会：
- 检查常用的 Ghostty 和 cmux 配置路径。
- 搜索有效的
theme = ...配置。 - 输出匹配的文件路径和行号。
- 忽略不存在的配置文件所产生的错误。
如果发现：
theme = One Dark
则需要根据第一步查询到的实际主题名称进行修正。
例如：
theme = Atom One Dark
或者使用其他已安装的主题：
theme = Catppuccin Mocha
如果不需要强制指定主题，也可以删除或注释这个配置项：
# theme = One Dark
此时 cmux 会根据剩余配置和默认主题机制决定终端配色。
本次问题在这一阶段就得到了解决，没有继续进入应用资源完整性检查或重新安装流程。
Step 3：重新加载配置
修改完成后，可以执行：
cmux reload-config
也可以使用快捷键：
Cmd + Shift + ,
cmux 会重新加载相关配置，不需要完全退出应用。
如果配置中的主题名称有效，且对应主题资源存在，原来的 theme not found 错误就不应再出现。
官方文档确认了 cmux reload-config 的使用方式。
五、如果问题依然存在怎么办？
如果修改主题名称后仍然出现错误，可以进一步检查 cmux 的 Ghostty 资源目录。
执行：
ls -ld \
"/Applications/cmux.app/Contents/Resources/ghostty/themes"
如果目录存在，可以搜索相关主题：
find \
"/Applications/cmux.app/Contents/Resources/ghostty/themes" \
-maxdepth 1 \
-iname "*one*dark*"
这能够帮助判断：
- 应用是否包含相应的主题资源。
- 主题文件名称是否与配置一致。
- 是否存在大小写或命名差异。
如果主题目录不存在，或者预期的主题文件缺失，才需要进一步调查 cmux 的安装完整性、资源路径或版本打包问题。
本次实际没有遇到这种情况。
六、这是不是 cmux 0.65.1 的 Bug？
排查过程中，我也查看了 cmux 的 GitHub Release 和相关 Pull Request。
发现一个比较有意思的改动：
PR #18271 — Filter pathless cmux-owned Ghostty diagnostics
该 PR 于 2026 年 10 月 7 日合并。
它修复了 cmux 在处理 Ghostty 配置诊断信息时的一类误报问题。
例如，cmux 自己使用的：
sidebar-font-size = 13
surface-tab-bar-font-size = 12
此前可能被 Ghostty 识别为未知字段，从而触发不必要的配置警告。
开发者通过改进诊断信息过滤逻辑，避免了这些由 cmux 自身配置字段导致的误报。
不过，这和本次遇到的情况存在区别。
本次错误信息明确指向：
theme "One Dark" not found
并且提供了具体的主题文件查找路径。
这说明配置解析器确实尝试加载该主题，但没有找到匹配的资源。
因此，目前没有证据表明本次问题由 cmux 0.65.1 的版本缺陷直接引起。
从排查结果看，主题名称与实际可用主题之间的不匹配，是更有解释力的原因。
七、延伸：如何更方便地管理 cmux 主题？
cmux 自身提供了主题管理 CLI，因此日常切换主题不一定需要手动修改配置文件。
例如，将主题设置为 Atom One Dark：
cmux themes set "Atom One Dark"
分别设置明暗主题：
cmux themes set \
--light "Catppuccin Latte" \
--dark "Atom One Dark"
清除 cmux 专属主题覆盖：
cmux themes clear
需要注意，themes clear 只负责清除 cmux 的主题覆盖设置，不会自动修复 Ghostty 共享配置中已经存在的无效主题名称。
此外，也可以自行创建主题文件：
mkdir -p ~/.config/ghostty/themes
然后将自定义主题保存到该目录：
~/.config/ghostty/themes/My Custom Theme
之后便可以通过：
theme = My Custom Theme
引用该主题。
对于同时使用 Ghostty 和 cmux 的用户，我更倾向于将共享的字体、主题和配色设置放在：
~/.config/ghostty/config
而将 cmux 独有的参数保留在：
~/Library/Application Support/com.cmuxterm.app/config.ghostty
这样可以尽量避免共享配置与应用专属配置之间的冲突。
八、总结
这次排查的是一个比较典型的终端配置兼容性问题。
在 cmux 0.65.1 中，启动时出现：
Ghostty 配置错误
theme "One Dark" not found
排查路径可以归纳为：
检查主题名称 → 查找实际配置来源 → 修正主题引用 → 重新加载配置。
对于类似问题，优先使用：
cmux themes list
确认主题名称，再检查：
~/.config/ghostty/config
以及：
~/Library/Application Support/com.cmuxterm.app/config.ghostty
通常能够快速定位问题。
这次也说明，在终端应用依赖第三方渲染引擎的架构下，理解配置文件的加载顺序、主题资源的查找路径，以及应用自身的覆盖机制，比直接重新安装软件更有助于准确排障。
最终，问题在配置检查阶段就得到了解决，无需重装 cmux，也不需要降级版本。