从零快速安装 niri 并跑通 Wayland 平铺合成器-平芜编程栈

从零快速安装 niri 并跑通 Wayland 平铺合成器

【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri

拖拽、对齐窗口，是日常桌面操作里最机械的一环。niri 是一款实现滚动平铺的 Wayland 合成器：新开的窗口自动进入分栏布局，按住 Mod 滚动滚轮即可切换工作区。按本指南的安装流程走完，你可以从一台裸机得到可登录的平铺桌面。

为什么值得试试

窗口自动落位：进入平铺布局的位置和宽度由布局引擎按列宽预设分配，不需要你手动挑位置。
滚轮切换工作区：工作区纵向排布，按住 Mod 滚动滚轮如同翻页，方向感比横向编号更直观。
快捷键负担小：聚焦、移动、关闭、全屏都有默认绑定，不用额外记忆组合键。
外观可配置：边框、焦点环、阴影、动画都能逐项调整，观感可按个人习惯微调。

环境准备清单

动手前对照下表确认，缺哪项先补哪项。

项目	要求
发行版	Ubuntu 24.04 及以上、Fedora 39 及以上、Arch 等主流发行版
内存	4GB 以上较稳妥
显卡	支持 Wayland 输出的显卡，主流厂商原生支持即可
构建工具链	能运行 cargo 的稳定版 Rust 工具链（下一节安装）

完整安装

装系统依赖

Ubuntu/Debian 下执行一行，把编译期需要的头文件与库带齐：

sudo apt-get install -y gcc clang libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev libpango1.0-dev libdisplay-info-dev

预期结果：所有包安装完成，无报错。

Fedora 使用对应的 dnf 命令，包名为 -devel 版本：

sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel cairo-gobject-devel clang libdisplay-info-devel

预期结果：依赖就绪，可直接进入编译阶段。

装工具链

系统里已有可用的 cargo 就跳过这步；否则用官方脚本装入最新稳定版：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

预期结果：rustc与cargo的版本号能正常打印。

拉代码编译

克隆仓库、进入目录，按 release 模式产出二进制：

git clone https://gitcode.com/GitHub_Trending/ni/niri cd niri cargo build --release

预期结果：target/release/niri生成完毕；首次构建耗时在分钟级，属正常现象。

注册为桌面登录会话

登录界面要出现 Niri 选项，需要启动脚本、.desktop 入口与 systemd user 服务三样就位：desktop 文件声明会话入口，niri-session负责拉起niri --session，service 则把它挂到图形会话生命周期上。按下面顺序复制并启用：

sudo cp target/release/niri /usr/local/bin/ sudo cp resources/niri-session /usr/local/bin/ sudo cp resources/niri.desktop /usr/local/share/wayland-sessions/ sudo cp resources/niri.service /etc/systemd/user/ sudo cp resources/niri-shutdown.target /etc/systemd/user/ systemctl --user daemon-reload && systemctl --user enable niri.service

预期结果：注销一次后，登录界面的会话列表里出现 Niri，选中登录即进入平铺桌面。

首次运行验证与最小配置

登录成功后按顺序确认三点：

连开两个终端窗口，确认它们自动进入分栏布局，无需手动摆位。
按住 Mod 上下滚动鼠标滚轮，工作区随之切换。
按 Super+T 启动 alacritty、Super+D 启动 fuzzel（两者需先自行安装）。

三项都正常，就可以开始整理配置了。niri 从~/.config/niri/config.kdl读取配置；该文件不存在时，首次启动会自动生成一份默认配置，直接在上面改即可。配置支持热重载，保存后即时生效。只想保留最基础的绑定，可以把binds {}段收敛成这样：

binds { Mod+T repeat=false { spawn "alacritty"; } Mod+Q repeat=false { close-window; } }

拿不准语法时，先在终端跑niri validate检查解析错误，再保存以免旧配置被拒绝加载。

常见坑速查

现象	可能原因	解决办法
编译报 gbm.h、wayland-client.h 等头文件缺失	发行版的开发包没装全	对照上文依赖清单补齐缺失的 -dev/-devel 包，重新编译
登录界面找不到 Niri 选项	.desktop 文件没放到约定目录，或二进制不在 PATH	确认`niri.desktop`已复制到`/usr/local/share/wayland-sessions/`，且`which niri`有路径输出
会话启动报权限错误、进程未以当前用户身份运行	直接加了 sudo 启动，或 user 服务没启用	通过`niri.service`这个 user 服务运行会话，不要对会话命令加 sudo
改了配置却不生效	KDL 语法出错，新配置被整体拒绝	运行`niri validate`定位报错行号，修好后再保存触发自动重载