如何安装Umbriel：AUR、Nix与源码构建3种路径终极指南（附依赖清单与常见问题）-平芜编程栈

【免费下载链接】umbriel

An independent compositor with scrolling, dwindle and master layouts, blur, shadows, and fluid animations.

项目地址：https://gitcode.com/gh_mirrors/umbr/umbriel

Umbriel 是一款基于 wlroots 构建的独立 Wayland 合成器（compositor），内置 scrolling、dwindle、master 三种布局，并支持模糊、阴影、流畅动画等视觉效果。本文覆盖AUR、Nix、源码构建三条 Umbriel 安装路径，附上完整依赖清单与常见问题解答，帮你快速完成安装并顺利启动第一个会话。

📦 30 秒快速决策：该选哪条安装路径？

你的系统	推荐路径	耗时	自动升级
Arch Linux / Arch 衍生版	AUR 一键安装	⭐ 最快	✅ 随 AUR 更新
NixOS / Home Manager 用户	Nix 模块 + 二进制缓存	⭐ 快	✅ flake 更新即可
其他发行版 / 想尝鲜最新代码	源码构建（`just`驱动）	⭐⭐⭐ 较慢	❌ 需手动更新

官方安装文档位于 docs/user/installation.md，打包细节见 PACKAGING.md。

🚀 路径一：AUR 一键安装（Arch Linux 最快路径）

Arch 用户最省心。AUR 提供umbriel-git包，一条命令完成编译与安装：

yay -S umbriel-git

💡 如果你还没装 AUR 助手，yay、paru等任选其一即可；命令形式略有差异，例如paru -S umbriel-git。

安装后，Umbriel 会注册umbriel.desktop显示管理器会话（见 data/umbriel.desktop 模板），在登录界面选择Umbriel即可进入；也可以在任何 TTY 下执行：

start-umbriel

📐 路径二：Nix 声明式安装（NixOS 与 Home Manager）

Nix 用户可以把 Umbriel 完全声明式地纳入系统配置。项目自带 NixOS 模块 nix/nixos-module.nix、Home Manager 模块 nix/home-module.nix 与包定义 nix/package.nix。

NixOS：启用系统模块

1️⃣ 在 flake 输入中加入 Umbriel：

{ inputs.umbriel.url = "github:noctalia-dev/umbriel"; }

2️⃣ 在系统配置中导入模块并启用：

{ inputs, ... }: { imports = [ inputs.umbriel.nixosModules.default ]; programs.umbriel.enable = true; }

该模块会自动完成：安装 Umbriel、注册显示管理器会话、启用图形支持，并安装配置好xdg-desktop-portal-umbriel（用于屏幕共享与录屏的 portal 后端）。

3️⃣nixos-rebuild switch后，在显示管理器中选择 Umbriel 会话，或在 TTY 执行start-umbriel。

⚡ 强烈建议：启用二进制缓存（Cachix）

不启用缓存意味着每次重建都要本地编译。将预构建的x86_64-linux与aarch64-linux缓存加入配置：

{ nix.settings = { extra-substituters = [ "https://umbriel.cachix.org" ]; extra-trusted-public-keys = [ "umbriel.cachix.org-1:JfNq/2yg2S6D6z4Z2dVSZrZlDPQTKtexB6GAVLD98nw=" ]; }; }

⚠️ 两个注意点：
使用缓存时不要设置inputs.umbriel.inputs.nixpkgs.follows，否则 store 路径不匹配；
建议追踪cachix分支（inputs.umbriel.url = "github:noctalia-dev/umbriel/cachix";），它指向 CI 成功缓存的最新提交，避免拉到没有二进制的新提交。

Home Manager：声明式配置

{ inputs, pkgs, ... }: { imports = [ inputs.umbriel.homeModules.default ]; programs.umbriel = { enable = true; settings = { general.autostart = [ "noctalia" ]; layout.gap = 5; keybinds = { "Mod+Return" = "spawn:kitty"; "Mod+Q" = "window-close"; }; }; }; }

settings用 Nix attrset 写法即可，模块会自动序列化为 TOML 写入~/.config/umbriel/config.toml；留空（null）则使用 Umbriel 打包的默认配置。

🔨 路径三：源码构建安装（通用 Linux）

其他发行版（Fedora、Debian、Ubuntu 等）可以走源码构建，或先查看「其他发行版」小节是否有现成仓库。

第 1 步：准备构建工具链

安装 C++23 编译器（GCC/Clang 均可）、meson、ninja、just、pkg-config、wayland-scanner，以及完整依赖（下一节清单）。

第 2 步：克隆、构建、安装

git clone https://gitcode.com/gh_mirrors/umbr/umbriel cd umbriel just release sudo just install

构建配方定义在 justfile：just release执行 release + LTO 编译，just install先确保构建再执行meson install。产物二进制位于build-release/umbriel。

💡 默认安装到/usr/local。不想用 root 权限？可以自定义前缀：
just prefix="$HOME/.local" release just install

其他发行版速览 🧭

Fedora：Terra 仓库提供umbriel-nightly，sudo dnf install umbriel-nightly
openSUSE：Noctalia OBS 仓库提供umbriel-git，zypper 添加仓库后sudo zypper install umbriel-git
Debian / Ubuntu：NickH APT 仓库提供umbriel包（仅amd64/arm64），需先安装签名密钥环再添加源
GNU Guix：通过第三方midnightchannel 安装umbriel与xdg-desktop-portal-umbriel

📋 完整依赖清单（源码构建必看）

以下为 PACKAGING.md 中的权威依赖声明（以 meson.build 为准）：

构建期依赖

依赖	版本要求	说明
C++23 编译器 + 标准库	支持 C++23	GCC / Clang
Meson / Ninja / pkg-config / wayland-scanner	—	构建工具链
just	—	任务运行器（本项目用其驱动构建）
wlroots	≥ 0.20.1 且 < 0.21	必须带 Xwayland 支持编译
wayland-server + client 库	≥ 1.24
wayland-protocols	≥ 1.47
xkbcommon / libinput	libinput ≥ 1.23	键盘布局与输入
libudev	—	原生`[drm]`GPU 排除功能需要
pixman	≥ 0.43
libdrm	≥ 2.4.129
libdisplay-info	≥ 0.3
Cairo / PangoCairo	—	文字渲染
tomlplusplus / nlohmann-json	—	配置与 JSON
xcb / xcb-icccm / xcb-ewmh	—	Xwayland 相关
EGL / GLES2 / GBM	—	渲染后端
lcms2	可选	缺省时仅保留参数化色彩转换
jemalloc	可选	glibc 上推荐，改善长会话内存表现

运行期依赖

依赖	作用
`Xwayland`（需在`PATH`中）	X11 应用支持
`xdg-desktop-portal-umbriel`	浏览器/OBS 等通过 portal 的屏幕共享
可用的字体栈	内部覆盖层与配置诊断界面
完整的 Wayland 图形/输入栈	DRM 原生运行或嵌套合成

📌 关于umbrielfx：Umbriel 的场景图与渲染器位于 umbrielfx/，是 SceneFX 的树内硬分叉，随源码一起编译，无需单独安装任何 scenefx 包。

🖥️ 启动 Umbriel 并准备你的配置

安装完成后有两种启动方式：

显示管理器 / TTY：选择 Umbriel 会话，或执行start-umbriel。它负责加载登录 shell 环境、（在 systemd 下）以umbriel.service管理合成器进程，并在会话结束时清理所有应用 scope。
直接运行umbriel：仅用于嵌套开发会话（在现有桌面里开一个嵌套窗口）或明确不托管的启动。

⚠️ 在 systemd 托管的原生会话中运行应用隔离需要systemd ≥ 254；较老的版本会退回直接启动路径。

首次使用建议复制打包配置作为起点（见 PACKAGING.md）：

mkdir -p ~/.config/umbriel cp /usr/share/umbriel/config.toml ~/.config/umbriel/config.toml

配置查找顺序为：~/.config/umbriel/config.toml→$XDG_CONFIG_DIRS下的umbriel/config.toml→ 打包的<datadir>/umbriel/config.toml→ 内置默认值。绝大多数修改保存即热重载，无需重启会话。完整可参考示例见 examples/config.toml。

❓ 常见问题（FAQ）

Q1：为什么不能直接运行umbriel，要用start-umbriel？start-umbriel会加载登录环境（PATH等变量对 Umbriel 及会话内应用生效）、以 systemd 用户服务管理生命周期。直接运行二进制仅适合嵌套开发或明确不托管的场景。

Q2：哪里看 Umbriel 日志？主日志在~/.cache/umbriel/umbriel.log（若设置了XDG_CACHE_HOME则在其下），达到 1 MiB 时轮转为umbriel.log.1。排查渲染/显示问题时，可设置UMBRIEL_WLR_DEBUG=1启动以包含 wlroots 调试输出。

Q3：X11 应用打不开？确认Xwayland二进制已安装且位于PATH中；配置里general.xwayland需为启用状态。

Q4：改了配置没生效？先确认 Umbriel 加载的是哪份配置（查找顺序见上文）；再用umbriel config validate离线校验语法。选中的配置文件若有语法错误，Umbriel 不会回退到下一份，而是保持最后一份有效配置生效并显示诊断信息。

Q5：构建失败提示缺少开发包？对照上文依赖清单逐项安装对应发行版的-dev包；注意 wlroots 版本必须落在0.20.1 ~ 0.21 之间，且带 Xwayland 支持。

Q6：装好了想先试试再进入正式桌面？可以嵌套运行：just run debug kitty会在当前桌面里打开一个嵌套的 Umbriel 窗口（此模式下 mod 键为 Alt，TTY 原生会话中为 Super）。