Omarchy 壁纸系统全解析：主题壁纸、自添加图片与视频动态壁纸配置指南

壁纸（Background）是 Omarchy 桌面系统“主题化”体验的组成部分：每个主题都随包自带一组壁纸，用户可以按主题目录自由补充图片，甚至放入视频文件让壁纸“动起来”。本文围绕 manual/39-backgrounds.md 展开，结合仓库中实际的壁纸渲染插件、CLI 工具与主题目录结构，讲解壁纸的存储约定、添加方式、选择/循环切换快捷键，以及视频壁纸的播放行为与性能代价，读完即可在任意主题下无缝加入自己的背景资源。

一、壁纸是主题的一部分：目录与状态约定

在 Omarchy 中，壁纸并不是一个孤立的全局设置，而是与主题绑定、随主题一起切换的资源。从 docs/theming.md 的主题规格可以看出，主题包内会随附 backgrounds/ 目录（第 10 行附近）；仓库中的主题资源也印证了这一点，例如 themes/nord/backgrounds/ 就自带了多张适配 nord 配色的壁纸（.jpg 与 .webp），并额外带有一张主题 Logo 壁纸 omarchy.webp。

其整体路径约定分为三层：

角色	路径	说明
主题自带壁纸（安装源）	themes/<name>/backgrounds/	仓库中各主题包内随附的壁纸资源
主题壁纸（运行时）	~/.local/state/omarchy/current/theme/backgrounds	应用主题时暂存/指向的当前主题壁纸目录
用户自添加壁纸	~/.config/omarchy/backgrounds/<theme>/	按主题名建立的用户扩展目录，与主题壁纸叠加

“当前使用哪张壁纸”是通过符号链接记录的：~/.local/state/omarchy/current/background。这在 docs/theming.md（“the active image is the ~/.local/state/omarchy/current/background symlink”）以及 shell/plugins/background/Background.qml 中的 currentBackgroundLink 属性中都可以得到确认——桌面背景渲染层正是靠 readlink -f 解析这条链接来获知当前壁纸路径的。

用户扩展目录与主题壁纸目录会被一并收集。以 bin/omarchy-theme-bg-next 为例，其搜索逻辑同时 find 用户目录与主题目录两个位置，并按文件名排序、做循环切换；同理，bin/omarchy-theme-bg-switcher 在弹出选择界面时也把“当前主题壁纸目录 + 当前主题用户壁纸目录”两者都传给了 omarchy-menu-images。

二、为任意主题添加自定义壁纸

原文档给出了最直接的添加路径：如果你想给某个主题（比如 nord）增加一张额外壁纸，只需把图片文件放进 ~/.config/omarchy/backgrounds/nord 即可。有以下两种推荐做法：

方式一：通过 Omarchy 菜单打开目录（推荐）

在 Omarchy Menu（Omarchy 菜单）中选择 Install > Style > Background。这会直接打开“当前主题”的用户壁纸目录：

• 底层对应的是 bin/omarchy-theme-bg-install 这个脚本，它会读取 ~/.local/state/omarchy/current/theme.name 拼出 $HOME/.config/omarchy/backgrounds/<当前主题名>；
• 目录不存在时自动 mkdir -p 创建，然后用文件管理器（nautilus）打开该目录。

因为打开的是文件管理器窗口，而目录窗口会占据整个窗口，原文档建议此时按 Super + Shift + F 再启动一个文件管理器，从另一个窗口中找到你想要的背景图片并复制过来。

方式二：手动直接复制

自己打开终端或文件管理器，把图片/视频复制到对应主题的用户目录即可，例如：

mkdir -p ~/.config/omarchy/backgrounds/nord
cp ~/Pictures/my-wallpaper.jpg ~/.config/omarchy/backgrounds/nord/

文件放进去后无需任何额外注册，它会立刻出现在壁纸候选列表中，可以被 Super + Ctrl + Space 选择。

支持的壁纸格式

依据 bin/omarchy-theme-bg-next 中实际的 find 过滤规则，静态图片与视频分别支持以下扩展名（大小写不敏感）：

• 静态图片：.jpg、.jpeg、.png、.gif、.bmp、.webp
• 视频壁纸：.mp4、.m4v、.mov、.webm、.mkv、.avi

三、选择与循环切换壁纸

图形化选择：Super + Ctrl + Space

按下 Super + Ctrl + Space 即可在当前主题的候选壁纸中挑选（见 manual/07-hotkeys.md）。该快捷键背后由 bin/omarchy-theme-bg-switcher 驱动：它会先读取当前主题名与当前背景链接，再把主题壁纸目录与用户壁纸目录中的所有资源交给 omarchy-menu-images 呈现为可视化选择界面，当前正在使用的壁纸会被标记为 --selected。选中的结果会通过 omarchy-theme-bg-set 写回状态并刷新桌面。

除快捷键外，Omarchy CLI 也注册了对应的别名入口：在 bin/omarchy-theme-bg-switcher 头部元数据中可以查到 omarchy background 别名；此外还有一个“直接切到下一张”的命令 bin/omarchy-theme-bg-next（其元数据示例为 omarchy theme bg next）。该脚本在主题目录找不到任何可用文件时会发送一条“未找到壁纸”的桌面通知，找到后则依据 background 符号链接定位当前壁纸的索引，取下一张并在末尾自动回绕（wrap around）。

桌面交互：双击桌面也能切换

如果你不方便记快捷键，也可以直接操作桌面：在 shell/plugins/background/Background.qml 中，壁纸层注册了一个覆盖全屏的 MouseArea——左键双击桌面会唤起壁纸选择器，右键双击桌面则会唤起主题切换器。这与 Super + Ctrl + Space 走的是同一条底层通道（bgSwitchProc / themeSwitchProc 两个 Process）。

当前状态如何被桌面感知

从源码看，这套机制依赖三个状态文件/链接：

• ~/.local/state/omarchy/current/theme.name：当前主题名（用于拼用户目录）；
• ~/.local/state/omarchy/current/theme/backgrounds：当前主题壁纸目录（运行时）；
• ~/.local/state/omarchy/current/background：当前壁纸的符号链接（被渲染层 readlink 解析）。

四、视频壁纸：播放、音频与自动暂停

除了静态图片，壁纸目录里的视频文件同样会被识别并以循环方式播放（这就是上一节列出的六种视频格式存在的意义）。原文档中的行为要点及其对应的源码证据如下。

音频只从第一台显示器出声

文档指出，“只有第一台显示器上的壁纸会播放视频音轨，通过默认音频输出、以系统音量播放”。这在 shell/plugins/background/Background.qml 中体现为 audioEnabled: panel.firstScreen：firstScreen 判断当前 PanelWindow 是否为 Quickshell.screens 列表中的第一块屏，只有主屏的媒体层会被打开音频，避免多块屏各自叠加同一份音轨。锁屏界面本身保持静音。

不可见即自动暂停

视频壁纸的播放并非始终运行，而是由三个条件共同决定是否“被看到”：

• 全屏窗口遮挡：某台显示器上有全屏窗口时，该显示器的壁纸暂停播放。源码中通过查询 Hyprland 当前 workspace 的 hasFullscreen 得到 fullscreenHere（Background.qml）；
• 屏幕保护（screensaver）运行：屏保窗口会覆盖所有输出，此时由 screensaverWindowCount > 0 判定；
• 锁屏后屏幕熄灭：锁屏服务被激活（lockActive）时同样暂停。

此外，当系统处于节电状态（powerSaverOnBattery，即电池供电的省电模式）时播放也会被禁用。代码里统一用 playbackEnabled: !sessionObscured && !powerSaverActive && !panel.fullscreenHere（见 Background.qml）表达这组暂停条件，其中 sessionObscured = lockActive || screensaverActive（第 46 行）。相关注释也解释了原因：Qt 的 FFmpeg 引擎自带播放时钟，一个“没人在看”的播放器如果不被明确叫停就会一直解码——锁屏的笔记本甚至会因此把电耗光。

性能代价：视频远高于静态图

视频壁纸在功耗上比静态壁纸高出很多，原因有两层：一是播放本身需要持续解码；二是源码实现中对每一台显示器都实例化了一个独立的壁纸窗口。在 Background.qml 中可以看到 Variants { model: Quickshell.screens } ——每个屏幕各有一份 BackgroundMedia，也就是说每台显示器都在独立解码一份自己的视频副本。因此多显示器 + 视频壁纸的组合，解码负担会随屏幕数量成倍增加。

五、深入原理：壁纸渲染层的实现细节

了解完用户侧操作，再看一眼渲染层 shell/plugins/background/Background.qml 的整体设计，能帮助你理解“换壁纸”为什么在 Omarchy 里显得顺滑自然。

图层角色。 背景以 WlrLayershell 的 Background 层呈现（namespace 为 omarchy-background），位于所有普通窗口之下、不拦截键盘焦点。每屏一个 PanelWindow，内部由一个统一的媒体组件 BackgroundMedia（定义于 shell/Ui/BackgroundMedia.qml）负责实际渲染。

图片与视频的分离加载。 BackgroundMedia.qml 内有两个 Loader：静态图片走 Image 组件；视频则按需从 BackgroundVideo.qml 加载。这样设计是为了让 QtMultimedia 及其音频依赖只在真正出现视频壁纸时才被映射进会话，纯图片会话不会白白加载整套多媒体栈。视频切换时会重建播放器（FFmpeg 会把 URL query 当作本地文件名的一部分，不能像图片那样用 ?v= 查询串做缓存失效，所以图片用 version 做 cache-bust，视频则通过 reloading 强制重建）。

切壁纸时的“揭示（reveal）”动画。 当从一张静态壁纸切到另一张时，源码会保留旧帧、载入新帧，并通过一个 420ms、Easing.InOutCubic 缓动的 NumberAnimation 驱动 revealProgress，配合 MultiEffect 的蒙版（一个带斜切的平行四边形遮罩）从屏幕中央向两侧展开过渡；而切到视频壁纸或涉及视频的切换则直接瞬间完成——既因为视频帧不经过这套仅针对图片的揭示栈，也因为这样可以避免在过渡期间同时解码两个全尺寸视频。主题整体切换时还会携带新的配色与 shell 状态（transitionBackgroundWithTheme），让壁纸与颜色在揭示动画完成点同步刷新。

状态同步。 壁纸层启动时会主动 readlink 当前背景链接（Component.onCompleted: refreshBackground()），并把 background、set、setInstant、transition、themeTransition 等操作暴露为 IPC 通道（IpcHandler），供 shell 的其它部件按需调用刷新。

六、获得更多壁纸素材

如果你觉得自带壁纸不够用，原文档还提示社区中有大量精心挑选（curated）的壁纸合集可供参考（dharmx/walls）。结合本文的机制，你可以直接把下载到的图片或视频复制进 ~/.config/omarchy/backgrounds/<主题名>/，再按 Super + Ctrl + Space 预览挑选；想要主题贴合度高，可以优先选择与当前主题配色相称的素材。

结语

Omarchy 的壁纸系统把“主题化”做到了位：壁纸随主题携带、按主题隔离的用户目录让资源可以零成本叠加；图片与视频共用一套目录约定，但渲染层对二者做了精细分流；视频壁纸的音频、暂停、功耗行为都有明确的规则并在源码中逐条落实。无论是想给喜欢的主题补一张墙纸，还是想体验动态视频桌面，你现在都清楚了该把文件放到哪里、用哪个快捷键切换，以及背后发生了什么。