更新后的配置维护：保留意图，比较差异，逐项迁移

更新完成，快捷键不工作，或窗口规则报错，但文件明明还在。原因可能是默认值变化、语法变化、迁移修改，或另一个配置层现在覆盖了你的设置。维护定制需要保留行为意图并适应变化，而不是永远冻结全部旧文件。

本页讨论个人配置。系统无法启动时，使用更新恢复与备份指南。系统快照和个人文件备份解决不同的失败。

1. 先判断设置属于谁

位置	归属与行为	维护方式
/usr/share/omarchy/	软件包管理的默认值和工具	不在这里保存个人修改
~/.config/hypr/	个人入口与覆盖	保留意图，检查语法和接口变化
~/.config/omarchy/shell.json	个人 Shell 行为与布局	编辑时保留其他键值
~/.config/omarchy/shell.toml	在主题之上的个人外观	检查支持的键与优先级
~/.local/state/omarchy/current/theme/	生成的当前主题	修改主题源文件或模板
Omarchy 开关状态	临时或持久模式	单独记录相关开关

个人目录适合定制，但不保证全部旧设置永远有效。合成器更新可能改变语法，迁移可能调整文件，配置刷新也可能替换它。生成的主题文件则会在应用主题时重建。

2. 更新前留下能解释的恢复点

记录 omarchy version、当前主题、相关开关和修改过的文件。每项定制写一句目标，例如“聊天在工作区 3 打开且不抢焦点”。语法变了以后，这句话比一段没有解释的代码更有用。

已有文件可以这样保存：

cp -i ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.before-update

使用新备份名称，其他实际修改过的文件分别保存。依赖自定义模板、钩子或插件设置的行为，也保存对应内容。需要防磁盘故障时，再留一份设备外备份；相邻文件只是方便的本地恢复点。

以后想做可靠的三方比较，还应保留当时使用的系统默认基准。图形会话定义了 OMARCHY_PATH 时，新安装的个人绑定模板位于 $OMARCHY_PATH/config/hypr/bindings.lua。它可能主要是注释，继承的默认快捷键还在 default/hypr/ 中，因此只保存个人模板不能保存全部默认行为。

3. 先比较失败，再决定是否复制回旧文件

omarchy version
hyprctl configerrors
omarchy menu keybindings --print

使用本机版本提供的命令。只有一个快捷键失败，就先看该文件和实际加载绑定；只有 Shell 异常，就检查它的 JSON/TOML 与插件状态，不要顺便改 Hyprland。

比较之前的个人文件与当前文件：

diff -u ~/.config/hypr/bindings.lua.before-update ~/.config/hypr/bindings.lua

diff 退出状态 1 表示找到差异，不表示比较失败。- 是旧文件移除的行，+ 是新文件增加的行，上下文说明它们在哪里。先读清新导入与工具函数，再决定哪些旧行应恢复。

比较对象	回答的问题
旧个人文件 → 当前个人文件	文件本身被改了吗
旧默认基准 → 新默认基准	系统改了什么
原目标 → 当前实际行为	定制是否仍完成任务

没有保存旧基准，就不能靠两份文件可靠地重建三方合并。查版本说明与对应源码，不要把每个差异都当成不该发生的系统修改。

4. 单文件配置刷新究竟做什么

本源码中的 omarchy-refresh-config 接受相对于 ~/.config 的路径：

omarchy-refresh-config hypr/bindings.lua

这是一项替换操作，不是查询。只有明确想采用新默认个人模板时才使用。工具把 $OMARCHY_PATH/config/hypr/bindings.lua 复制到个人文件；内容不同时，旧文件保留为 bindings.lua.bak.<timestamp>。完全相同则不保留多余备份；系统配置树中没有的路径会被拒绝。

刷新不保证所有相关应用都自动重载。比较后逐项加回必要修改，再通过正常配置菜单应用，检查真实行为。

只查找备份，不修改它们：

find ~/.config/hypr -maxdepth 1 -type f -name 'bindings.lua.bak*' -print

根据内容和修改背景选择备份，不只按最新文件名选择。迁移脚本可能用其他备份名称和逻辑；这个时间戳模式只描述该工具，不代表所有更新步骤。

5. 迁移小目标，不整套复制旧桌面

假设旧快捷键使用 .conf 语法，新入口已经加载 Lua。把旧块贴进 bindings.lua 不能保留功能。先找出原按键、命令和行为，再用当前工具函数表达：

o.rebind("SUPER + SHIFT + F", "Open Documents", {
  launch = 'nautilus "$HOME/Documents"',
})

这里只在按键和已有路径适合本机时才是有效例子。单独测试命令，一次保存一个变化，再试按键。第一项正常以后再迁移下一项；完整流程见快捷键教程。

确认当前入口必需的新初始化和导入行后保留它们。窗口规则重新检查真实应用标识并用新窗口测试；主题模板重新切换主题，看生成结果。语法正确不等于原行为保留。

6. 恢复最小的必要范围

恢复方法	适用情况	注意影响
撤销一行	一个新修改导致问题	影响最小
恢复一个文件	旧文件仍与当前版本兼容	会替换该文件后来的修改
刷新一份默认配置	明确需要新基准	比较后再加回个人意图
重置全部配置	明确放弃当前个人设置	大范围覆盖，不是普通撤销

不要把 omarchy reinstall configs 当作教程的例行最后一步。本源码会将软件包的 /etc/skel 树复制覆盖到家目录，涉及随包提供的 dotfiles 和其他默认内容，并运行额外刷新步骤。它比“修复一个绑定”广得多，也不会完整备份你的旧环境。

恢复一个文件以后，检查错误、完成真实任务，并验证菜单和终端等其他入口。若更新引入不兼容接口，反复复制回同一旧文件只会重复出现错误。

7. 留下以后能接着维护的记录

把受影响版本、来源、修改文件、行为目标、备份位置和验证结果记录在一起。不再需要的临时方案，验证正常支持路径后移除；长期叠加覆盖可能隐藏系统改进，也让排查更困难。

需要报告问题时，按求助模板提供最小相关配置片段与具体错误，分享前去掉凭据、私人路径和无关日志。

来源与关联指南

单文件刷新源码 · 全部配置重置 · 更新流程 · 官方更新说明

继续阅读配置如何生效或备份与恢复。