---
title: Matugen：从配色生成到应用刷新
url: https://doc.liz6.com/tools/hyprland/06-matugen
locale: zh
area: tools
tags:
- Hyprland
- 开发工具
- Hyprland 桌面
date: 2026-09-15
modified: 2026-09-15
description: 用独立示例理解输入颜色、语义角色、模板输出与重载，并说明 Caelestia 与应用主题的同步边界。
---

# Matugen：从配色生成到应用刷新

Matugen 根据图片或颜色生成调色板，再把颜色填入模板。应用是否立即变色，还取决于它怎样读取主题文件以及是否支持重载。排错时应把“生成”和“刷新”分开。

本文示例以 Matugen 4.1.0 为核对版本。先用独立目录完成实验，再接入正式桌面配置，避免生成过程覆盖正在使用的主题。

## 配色链的四个环节

| 环节 | 产物 | 常见问题 |
| --- | --- | --- |
| 输入 | 壁纸路径、种子颜色、明暗模式 | 图片不存在，模式与外壳不一致 |
| 生成 | primary、surface、on_surface 等角色 | 选错 scheme 或角色 |
| 模板 | Ghostty、GTK、Waybar 等格式的文件 | 模板语法错误，输出路径不对 |
| 刷新 | 当前应用读取新配置 | 文件已更新，进程仍使用旧内容 |

`surface` 适合作为表面背景，`on_surface` 是对应前景角色，`primary` 用于强调。直接挑三个看起来好看的颜色，可能破坏文字与背景之间的关系；还应在应用中检查禁用、选中和警告状态。

## 先在独立目录生成

建立一个新的练习目录并进入，例如 `matugen-lab`。保存下面的 `ghostty.template`：

```text
background = {{colors.surface.default.hex}}
foreground = {{colors.on_surface.default.hex}}
cursor-color = {{colors.primary.default.hex}}
```

同目录保存 `config.toml`：

```toml
[config]

[templates.terminal]
input_path = "ghostty.template"
output_path = "generated.theme"
```

从这个目录运行，显式指定配置文件：

```bash
matugen -c ./config.toml color hex '#6750a4'
```

查看生成结果：

```bash
cat generated.theme
```

应看到三项实际颜色，没有残留 `{{...}}`。4.1.0 的 `.hex` 值已经带 `#`，模板不能再手工加一个 `#`；否则 GTK CSS 等目标可能得到 `##...`。升级模板引擎后，先在这里验证变量格式，再调整正式输出。[Matugen](https://github.com/InioX/matugen)

颜色作为输入便于复现。改成壁纸时，将命令换为 `matugen -c ./config.toml image ./wallpaper.png`，并确保图片存在。明暗模式可以通过 `--mode light` / `--mode dark` 指定。

## 为每个应用编写自己的模板

同一个角色需要转换成目标应用接受的语法。Waybar 使用 GTK CSS，模板可以是：

```css
@define-color main-bg {{colors.surface.default.hex}};
@define-color main-fg {{colors.on_surface.default.hex}};
@define-color accent {{colors.primary.default.hex}};
```

Ghostty 的主题使用 `key = value`，Zellij 使用 KDL，不能把同一份输出直接复制给所有应用。先让每个应用用静态颜色正常工作，再用模板生成相同结构。

正式配置中的每个模板应写明输入和输出路径。输出目录需要存在且可写，文件应只包含该应用需要的语法。对有配置校验器的应用，先校验临时输出，再将其发布到正式主题路径。

## post_hook 与刷新策略

Matugen 的模板可以关联生成后的 hook。hook 负责通知应用重新读取配置，不应替代生成结果检查。最初接入时先不设置 hook，确认文件正确后再加刷新动作。

| 应用 | 建议验证方式 |
| --- | --- |
| Ghostty | 生成 themes 文件，执行配置检查，再测试其重载动作 |
| Waybar | 使用独立测试配置；正确后重载指定实例或对应服务 |
| GTK 应用 | 检查生成 CSS；部分应用需要新建窗口或重启 |
| Zellij | 检查 KDL 主题和所选主题名，区分新会话与现有会话 |
| 外壳 | 使用该外壳公开的主题接口与配置约定 |

不要把某个应用支持的 `SIGUSR2` 推广到所有程序。旧配置向终端广播 OSC 颜色序列是自定义脚本行为；它有终端实例选择、复用器转发和应用覆盖颜色等边界。需要热更新时，优先使用目标应用明确支持的机制。

## 当前 Caelestia 实例如何连接

当前本地流程由 Caelestia 选择壁纸、明暗模式和方案，再通过 `caelestia-sync-app-theme` 脚本映射到 Matugen 参数。脚本读取当前壁纸状态，对 scheme 名称做转换，并用文件锁避免并发生成。

Matugen 配置包含 Ghostty、Zellij、GTK、KDE、Fuzzel 和 Fcitx5 等输出。Caelestia 外壳本身有自己的主题状态，并不是继续读取 ii 时代的 Quickshell `colors.json`。

共同壁纸不保证每个界面像素颜色完全相同，因为外壳与模板可能使用不同角色和生成选项。应验证输入、模式与角色选择是否一致，再判断差异是否需要调整。

## 一处没有更新时怎样定位

1. 确认此次使用的图片路径、模式和配置文件；不要只检查旧默认配置。
2. 在独立目录运行同样的生成命令，检查退出状态和输出内容。
3. 比较正式输出路径、修改时间与应用实际读取的路径。
4. 单独执行应用支持的重载操作，检查其日志。
5. 若新窗口正确、旧窗口不变，继续查运行时刷新能力；若二者都错误，回查模板与主题选择。

恢复时先还原主题文件和应用配置，再按应用支持的方式重载。多应用生成并不是天然的全局事务，某个模板失败后可能存在部分更新，应逐项核对。