Omarchy 桌面入门：安装、开发与安全维护
Omarchy 是一套已经选好桌面组件、外观和操作习惯的 Linux 桌面系统。它适合希望在本机写代码、使用终端，并愿意学习键盘操作的人。安装它会改变整台电脑的系统环境，不是给现有桌面换一张壁纸。
本指南先帮助你判断是否适合安装，再完成一次本地小项目，最后说明更新、定制和恢复的方法。已经装好的读者可以从“第一次进入桌面”开始；准备替换工作电脑的读者应先完成备份和安装方式的选择。
Omarchy、Arch Linux 和 Hyprland 分别做什么
按当前官方手册，Omarchy 把 Arch Linux、Hyprland 和 Quickshell 整合为一套桌面：
Wayland 是 Linux 图形应用与显示系统通信的一套协议；合成器负责组织窗口并把画面显示出来。终端则是输入命令的应用，终端里解释命令的程序叫 shell。Quickshell 虽然名字里也有 shell，在这里负责的是桌面界面，不是解释终端命令。
Arch 持续更新软件包，而不是让用户只在少数大版本之间升级。Omarchy 在这个基础上增加自己的发布和更新安排。因此，“使用 Arch 软件包”不等于“任何 Arch 教程都能直接照做”。
哪类桌面更适合你
下表是选择思路，不是速度、稳定性或安全性的排名。
先列出必须工作的功能：视频会议、中文输入、外接屏、休眠、特定专业软件。最好先在备用设备或有恢复方案的测试环境中验证，别把外观相似当成兼容性保证。本页不提供未经验证的最低内存、CPU 或磁盘容量，也不保证所有笔记本都适用。
本文使用哪个版本的说明
截至 2026-09-12，官方 latest-release 接口报告的稳定版为 v4.0.3，发布时间为 2026-09-08 19:50:46 UTC，不是预发布版。接口跳转到当前的 omacom/omarchy 仓库。这个日期描述的是当时查到的发布状态；安装时仍应重新查看发布页。
本文按 v4 的 Lua 配置、Quickshell 和 Foot 终端说明操作。不要把旧教程里的 hyprland.conf、Waybar 或旧版供应商目录照搬进来。Omarchy 版本号也不能用来推断内核、Hyprland 或显卡驱动的版本。已有 v3 系统应先备份，再查对应的官方迁移说明，不要用本文的路径自行拼出迁移流程。
安装前：先决定哪块盘可以改动
准备好可恢复的环境
官方安装说明是实际安装时的依据。开始前准备：
- 可以从安装 USB 启动的目标电脑，以及可靠的供电和可用网络。
- 可以覆盖内容的 USB 盘；写入 ISO 镜像会替换 USB 上原有内容。
- 已确认身份的目标物理磁盘。记下型号、容量和用途，不只凭“第一块盘”判断。
- 独立于目标磁盘的文件备份，以及恢复原系统所需的安装介质和恢复资料。
- 有线键盘或带 2.4 GHz 接收器的键盘。官方手册说明蓝牙键盘不能用于开机前的磁盘解锁提示。
备份至少包括个人文件、未提交的项目修改和需要保留的配置。实际从备份恢复一个样本文件，再继续。加密密钥和恢复资料应私下妥善保存，不要贴进求助日志。
整盘安装与空闲空间安装
当前安装器提供两条不同的路线，不能混为一谈：
两条路线都默认启用磁盘加密。加密主要保护关机后磁盘上的数据，不会替你备份文件，也不能替代已登录会话的访问控制。除非清楚理解改变后的风险，否则保留默认加密设置。安装方式与加密默认值
固件设置：Secure Boot 和 TPM
Secure Boot 用于验证启动软件，TPM 是可保存密钥和参与设备安全检查的硬件安全组件。它们并非 Windows 专属技术。
Omarchy 当前安装手册要求在安装前禁用 Secure Boot 和／或 TPM。把它当作这套安装流程的要求，而不是通用 Linux 结论。修改这些设置可能影响另一套系统的启动或磁盘解锁；先查原系统及设备厂商的恢复说明，再决定是否继续。不要清除 TPM，也不要在没有恢复方案时试改固件安全选项。 如果设备由单位管理，应先确认是否允许这些改动。官方安装要求
从 ISO 到首次启动
ISO 是安装介质的镜像文件。以下步骤会写入存储设备，不属于无损试用：
- 从官方安装页或发布页进入下载链接，不使用来源不明的重打包镜像。
- 按手册选择写盘工具：macOS / Windows 使用 balenaEtcher，Linux 使用 caligula。按官方入口获取工具。
- 在写盘工具中再次核对目标 USB 的型号和容量。确认其中没有要保留的文件，再写入镜像。
- 按设备厂商的方法打开启动菜单，从 USB 启动。若无法启动，先检查启动设备和安装手册中的固件要求，不要随意更改其他磁盘设置。
- 选择已经确认过的目标磁盘和安装方式。逐项阅读最后的确认内容；如果它与原先的磁盘计划不一致，取消安装。
- 完成安装器的提示后，按提示重启进入已安装系统。保留 USB 作为可能需要的恢复介质。
写入安装 USB 和安装到电脑磁盘是两次独立的选盘操作。前一次选对 USB，不代表后一次自动选对系统盘；两次都要核对目标设备。
Windows 双启动的独立分支
官方 Windows 双启动流程要求先关闭 BitLocker／设备加密，并等待解密完成，再在 Windows 的“磁盘管理”中压缩卷，留出未分配空间。加密状态和恢复资料应在 Windows 侧确认，不要仅凭 Linux 能看到分区就继续。
然后从 Omarchy USB 启动，选定物理盘后选择 Free space install。手册举的 50 GB 只是示例，不是最低容量承诺；空间还要容纳你的项目、应用和后续数据。Omarchy 这一侧仍默认使用 LUKS 磁盘加密。
当前手册使用 Limine 启动管理器，并记录了用 limine-scan 发现 Windows Boot Manager 的方法。这个命令会改变启动配置，不能当成只读检查随手运行。只有在符合手册所述情形时才按对应流程处理。双启动菜单能显示两个系统，也不能证明所有磁盘布局都安全。
第一次进入桌面
目标是先完成一次“开菜单、找应用、用终端、再回到菜单”的操作，不必背下整张快捷键表。
- 用准备好的键盘解锁磁盘，进入桌面。
- 按 Super+Space 打开 Omarchy 菜单。Super 在许多 PC 键盘上是带 Windows 标志的键；实际映射以本机配置为准。
- 通过顶栏面板检查网络和音量，再在 Setup > Input 查看键盘设置，避免把键盘布局问题误当作快捷键失效。
- 从桌面的应用入口找到并打开默认终端 Foot。不熟悉入口时先用菜单查找，不套用别的 Hyprland 配置的启动快捷键。
- 打开一个已安装应用，完成一次简单操作，再关闭窗口并重新打开菜单。
- 到 Setup > Keybindings 查看本机键位。有需要时再学习其中常用的几项。
这些菜单入口见更新说明和配置说明；网络、音量等面板见顶栏手册。当前顶栏手册还记录了 Super+Ctrl+D 打开显示面板，以及 Super+Shift+Space 切换顶栏可见性。顶栏隐藏时，先检查是否误触了切换键，不急着重置配置。
在终端确认自己所处的环境
以下命令只读取本机状态，不安装软件，也不需要 sudo：
cat /etc/os-release
uname -r
printf '%s\n' "$XDG_SESSION_TYPE"
pacman -Q omarchy
pacman -Qs foot
前两项分别显示操作系统信息和正在运行的内核版本；会话变量在正常的 Wayland 桌面中通常显示 wayland，但它不能证明每个应用都以原生 Wayland 方式运行。
pacman -Q omarchy 查询本地同名软件包；如果显示找不到包，先检查实际包装方式和系统版本，不能据此认定没有安装 Omarchy。pacman -Qs foot 搜索已安装软件包的名称和描述，不会刷新仓库数据库。输出因本机而异，不必和别人的截图逐字相同。
实践：在本机写一个小程序并测试
这个练习把终端、文件和测试串起来，不安装软件，不联网，也不改系统配置。使用通常已有的 sh 和文件工具，因此不依赖某个语言运行时是否预装。所有文件都留在一个新建的个人目录中。
1. 检查工具并建立练习目录
在 Foot 中逐条检查：
command -v sh
command -v mktemp
command -v cat
每项都应显示命令路径；空输出或非零退出状态表示当前 shell 没找到该命令。缺少工具时先停下，查本机环境，不从陌生网页粘贴安装脚本。
下面创建一个带随机后缀的新目录，不覆盖已有项目。请在同一个终端中操作：
project_dir=$(mktemp -d "$HOME/omarchy-practice.XXXXXX")
成功时通常没有输出。继续进入它：
cd -- "$project_dir"
pwd
pwd 应显示你家目录下的 omarchy-practice. 加随机后缀的路径。如果创建目录或 cd 报错，先停下，不要在未知目录里执行下一步。这个变量只在当前 shell 中保留；稍后可以通过 pwd 显示的路径重新打开项目。
2. 写程序
cat > greet.sh <<'EOF'
#!/bin/sh
name=${1:-Omarchy}
printf 'Hello, %s!\n' "$name"
EOF
sh greet.sh
sh greet.sh 'Linux learner'
预期输出依次为：
Hello, Omarchy!
Hello, Linux learner!
greet.sh 是程序文件；${1:-Omarchy} 表示第一个参数存在且非空时使用它，否则使用默认名字。引号让带空格的名字作为一个参数传入。用 sh greet.sh 运行不需要修改文件的执行权限。
cat 后面的带引号分隔符让 shell 原样写入程序文本，而不是在写文件时提前展开变量。这里的 > 会覆盖同名文件，因此练习必须在刚创建的目录中进行。
3. 给两种行为写测试
测试用明确的预期结果检查程序，而不是只看“没有报错”。
cat > test-greet.sh <<'EOF'
#!/bin/sh
set -eu
test "$(sh ./greet.sh)" = 'Hello, Omarchy!'
test "$(sh ./greet.sh 'Linux learner')" = 'Hello, Linux learner!'
printf '%s\n' 'PASS: default and named greetings'
EOF
sh test-greet.sh
预期看到：
PASS: default and named greetings
test 比较实际输出和预期文本；set -e 使这里失败的测试停止脚本，set -u 帮助发现未设置的变量。只有两项都通过才会打印 PASS。
如果程序文件找不到，先用 pwd 和 ls 确认两个文件在同一个目录。如果输出不符，用 sh greet.sh 单独检查标点和空格。不要为了让测试通过而盲目删除检查项。
现在可以从编辑器打开 greet.sh，修改问候语，再运行测试观察结果。保留这两个小文件即可，无须执行清理命令。要开始记录项目历史，继续阅读 Git 与 GitHub；编辑器操作见 Vim。
换成真正的开发项目
先检查工具，而不是假定所有开发栈都已预装：
command -v git
command -v python
command -v uv
command -v node
command -v docker
没有找到某个命令并不意味着 Omarchy 安装失败。选定项目需要的语言后，按该工具的官方方法准备环境；不要一次安装所有编译器、数据库和服务。
Python 项目可按 uv 环境指南把依赖放进项目环境，不使用 sudo pip，也不把应用依赖直接塞进系统 Python。能找到 docker 命令只说明客户端存在，不能证明服务已启动或当前用户有访问权限。不要为了“先跑起来”随意改变系统权限。
需要长时间保留终端工作时，参考 tmux。部署到远程主机时，转到 个人 VPS 基础：这里的 Omarchy 是本地桌面，VPS 是另一台系统，更新和防火墙命令不能混着执行。密码、访问令牌和私钥都不应写进示例、共享配置或 shell 历史。
更新系统与管理软件包
用 Omarchy 的更新入口
完整更新会协调系统及其依赖的版本；Omarchy 还需要执行自身的迁移和配置处理。官方更新说明把 Update > Omarchy 与下面的命令作为同一条受支持路径：
omarchy update
这条命令会改变已安装系统。 更新前保存工作、确认独立备份可用，留出处理错误和重启的时间；不要同时运行另一个包管理事务。该流程处理 Omarchy 发布、迁移、系统／AUR 更新及快照。按输出完成必要步骤，再确认日常应用还能工作。
当前 Omarchy 通过常规 pacman 软件包安装，不只是复制到另一套桌面上的配置文件。手册说明 stable 是默认频道，跟随正式发布，并使用比 Arch 上游晚一个月的 Omarchy 镜像。这是当前更新策略，不是永久承诺或安全响应时限。
直接运行 pacman -Syu 或 yay -Syu 会绕过 Omarchy 的快照、迁移和配置流程，当前手册将其作为受保护的路径。不要绕过保护，也不要因为另一篇 Arch 教程用了它们就替换官方更新入口。固件更新属于单独的 Update > Firmware 流程，使用 fwupd，可能需要重启；不是每台设备都一定有可用的固件更新。
为什么不能只刷新包列表
pacman 是 Arch 的底层包管理器。仓库数据库记录可用软件包及版本，已安装软件包则是本机正在使用的文件。只刷新数据库再选择性安装，可能让新软件依赖比现有系统更新的库。
Arch 明确不支持部分升级。不要运行 pacman -Sy，也不要运行 pacman -Sy package。 如果同步后事务失败，应先排除问题并完成完整更新，再进行其他包操作。Arch 的通用维护原则解释了风险，但不替代 Omarchy 的更新流程。
官方软件包与 AUR
AUR（Arch User Repository）提供社区维护的构建说明，不是与官方仓库等同的信任来源。安装时可能执行这些构建指令；使用 AUR 助手或看到高人气都不能代替检查。安装前阅读构建文件和来源，不能判断时先不装。系统库的二进制接口变化后，某些 AUR 包还需要重新构建。Arch 维护建议
日常了解本机包状态可以使用：
pacman -Qs foot
pacman -Qm
第一条搜索已安装包信息；第二条列出不属于当前同步仓库的外来包。这些包可能来自 AUR，也可能来自其他渠道，不能把输出直接叫作“AUR 清单”。两条命令都不安装软件、不刷新数据库。
下面的 Joplin 例子使用手册实际给出的 Omarchy 添加软件命令。它是可选练习，不是桌面入门的前提；涉及社区包时，先完成构建说明的检查，不使用未经核对的通用安装替代命令。
定制配置：知道什么归自己维护
当前配置手册将用户配置放在 ~/.config 下，供应商文件放在 /usr/share/omarchy。不要直接修改供应商目录；升级可能替换它，也会使问题更难追踪。
表格中缩写的文件名都位于前述 ~/.config/hypr/ 目录。手册说明个人 .bashrc 中的别名和函数不会被覆盖，但重要修改仍应保留备份。
优先从 Setup > Monitors / Keybindings / Input / Config 进入对应编辑器，这些入口会处理编辑后所需的重启。默认编辑器为 Neovim：普通模式用于操作文本，按 i 进入插入模式；写完按 Esc 回到普通模式，输入 :wq 并回车保存退出。放弃未保存修改可用 :q!。更完整的编辑方法见 Vim 指南。
可撤销的例子：为 Joplin 绑定一个按键
仅在确实需要 Joplin 时做这一节。官方配置页给出了这组软件命令和 Lua 示例。先确认是在 v4，并且 ~/.config/hypr/bindings.lua 已存在；文件缺失时停下，不自行创建一个猜测的新版配置。
-
准备好完整更新后的系统，检查相应包的构建说明，再安装应用。这一步会改变系统：
omarchy-pkg-add joplin-bin -
先从应用入口打开 Joplin，确认应用本身能运行；若失败，先解决应用问题，不靠更换快捷键来修复。
-
在终端给现有键位文件留一份本地副本：
cp -i -- ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.before-edit如果目标副本已存在，
-i会询问是否覆盖。不要覆盖唯一一份已知可用的副本；需要保留它时取消并另选文件名。这只是同一磁盘上的配置副本，不是灾难恢复备份。 -
打开 Setup > Keybindings，先查看 Super+Shift+O 当前绑定的动作。只有接受替换该动作时，才加入手册的示例：
hl.unbind("SUPER + SHIFT + O")o.bind("SUPER + SHIFT + O", "Joplin", "joplin-desktop") -
保存退出，让菜单流程处理重载，再按组合键。预期打开 Joplin；如果应用能直接打开但按键无效，检查拼写、重复绑定和重载时的错误。
要撤销本次编辑，在确认副本确实是所需旧状态后执行：
cp -i -- ~/.config/hypr/bindings.lua.before-edit ~/.config/hypr/bindings.lua
这会替换当前文件，连同备份之后的其他改动一起撤回。随后通过相同的 Setup 入口保存退出，完成对应重载。还原绑定不会卸载 Joplin。
顶栏和终端的特殊之处
自定义 shell.json 会替换整套默认配置，而不是递归合并。因此未来默认新增的小组件不会自动出现在你的自定义顶栏里。更新后缺少某个小组件时，先比较配置，不必立即认定更新失败。顶栏配置规则
omarchy bar defaults 会恢复顶栏默认配置，丢弃相应定制；它不是无害的检查命令。执行前先保存需要保留的配置。调整 Foot 字体后，用新开的终端窗口观察结果；已有窗口不会重新加载字体变化。显示设置说明
显示、输入和硬件问题怎样排查
HiDPI 与多显示器
HiDPI 指屏幕像素密度较高；缩放用于让文字和控件保持合适大小。先通过显示面板调整，而不是从别人的配置复制输出名称。查看本机实际输出：
hyprctl monitors
显示器手册记录了显示面板、Hyprmon 终端界面以及 Setup > Monitors 对应的 monitors.lua 和 hl.monitor 规则。先记下实际输出名称、可用模式和当前缩放，每次只改一个显示器，确认可用后再处理另一个。Lua 规则的写法应从当前手册获取，不把旧版 Hyprland 配置语法改个扩展名就使用。
外接屏能被列出却没有正常画面，与完全检测不到输出是两类问题。前者先查启用状态、模式和布局，后者再检查连接、扩展坞及驱动信息。混合不同像素密度的屏幕时，用新开的应用窗口验证文字大小和移动窗口后的表现；没有一个通用缩放值适合所有屏幕。
显示器缩放与 GDK_SCALE 不是同一个控制项，后者是某些 GTK 应用使用的整数缩放设置。不要为修一个应用就全局叠加缩放变量；先确定问题影响整个桌面还是单个应用。
屏幕共享、输入法和 NVIDIA
这些功能受应用、驱动及 Omarchy 打包的组件版本影响。先缩小问题范围，再核对适用的官方说明，避免一次替换多个组件。
Wayland 应用常通过桌面 portal 服务请求屏幕共享，让桌面向用户询问共享哪个屏幕或窗口。缺少选择对话框与选择后黑屏需要不同的调查，不应一开始就更换包。进一步阅读 Hyprland 屏幕共享、Hyprland NVIDIA和 Arch Fcitx5。这些是上游排查入口，不是已经确认适用于所有 Omarchy v4 设备的配置处方；采用具体步骤前要核对本机组件版本和 Omarchy 的整合方式。
收集小而有用的诊断信息
以下是普通的本机只读检查，无须 sudo：
cat /etc/os-release
uname -r
printf '%s\n' "$XDG_SESSION_TYPE"
hyprctl monitors
systemctl --user --failed
journalctl --user -b -p warning --no-pager -n 80
最后两条分别查看失败的用户服务，以及本次启动中最多 80 条用户级警告及更严重的日志。没有失败服务也不代表应用没有问题；日志中有警告也不等于每条都要修。hyprctl 应在正常的 Hyprland 会话里使用，在恢复终端里连接失败不能单独证明显卡坏了。
求助时附上具体动作、预期结果、实际现象、最后一次改动和相关的少量日志。日志可能带有用户名、文件路径、网络标识和应用信息，先在本地检查并删去隐私。不要把整份配置目录、凭据或无关日志直接上传。
恢复：小改动、坏更新和磁盘故障分别处理
恢复方法应对应故障范围：
Omarchy 更新流程会创建快照，手册建议在坏更新后尝试启动之前的快照。官方更新与恢复说明并不因此保证每个家目录文件都被包含，也不能把快照保留数量当作固定承诺。同一磁盘上的快照仍会随着磁盘故障一起失去。
遇到故障时按影响从小到大处理：
- 记录现象和最后一次改动，停止叠加不相关的修复命令。
- 如果刚编辑了一个配置，且还能进入可用会话，先还原那一个文件并按对应流程重载。
- 如果紧接着系统更新出错，按手册从启动界面选择之前的快照；进入后检查影响工作的功能，再决定下一步。
- 如果正常启动路径不可用，使用保留的恢复介质并查对应官方说明。不要凭猜测改分区、重写启动器或递归修改系统权限。
- 只有在保留个人配置并理解重置后果后，才考虑重置或重装相关选项。
omarchy reinstall 是重置操作：可能覆盖用户配置、返回 stable，并将过新的包降级。Update > Config 和 omarchy reinstall configs 也应作为会影响配置的操作对待，不应因为一处小问题就先执行它们。安装、重大更新或重置前，都要把重要工作保存在目标磁盘之外，并确认至少一个样本文件可以恢复。