niri 完整配置指南：三步跑通可滚动平铺 Wayland 桌面

niri 完整配置指南：三步跑通可滚动平铺 Wayland 桌面

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

niri 是一个可滚动平铺的 Wayland 合成器：窗口按"列"排布在一条向右无限延伸的带子上，打开新窗口不会挤压已有窗口，左右滚动就能翻遍全部窗口。工作区则像 GNOME 一样在垂直方向动态生成，每台显示器各自独立一套。配置文件是一份 KDL 格式的config.kdl，支持热重载，改完保存立即生效。

第一天：安装并启动

niri 本身不是完整的桌面环境，只是窗口管理核心，通常搭配一个桌面壳（如 Quickshell 系方案）使用。获取方式有三条路：

从源码构建时，先克隆仓库：

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

注意：不要加--all-features构建，部分 feature 只用于开发，其中一个会让 profile 缓冲区无限增长直到内存耗尽。

没有显示管理器时，在 TTY 里执行niri-session（systemd/dinit 环境）或niri --session启动。首次登录后记住几个默认快捷键（TTY 下 Mod 即 Super 键）：

• Mod+T打开终端，Mod+D打开应用启动器
• Mod+H / Mod+L / Mod+J / Mod+K聚焦左、右、下、上的列或窗口
• Ctrl 叠加上面这些键= 把窗口"搬"过去，而不是只移动焦点
• Mod+U / Mod+I上下切换工作区；Mod+Shift+F全屏；Mod+V平铺/浮动互切
• PrtSc区域截图（选区后按 Space 保存）
• Mod+Shift+E退出；Mod+Shift+/随时调出快捷键速查表

认识 config.kdl：一处配置，热重载生效

niri 从~/.config/niri/config.kdl读配置（找不到时回退到/etc/niri/config.kdl，两者都没有则自动生成默认配置）。KDL 语法只需三点就够上手：

• //是注释；/-section可整段注释
• 开关类选项直接写名字即开启，注释掉即关闭，例如focus-follows-mouse
• 同名区块大多不能重复，按设备名区分的区块（如多个output）除外

最关键的性质：保存即生效。键绑定、输出模式、窗口规则全部热重载，不需要重启合成器。改乱了也不怕，跑一条命令体检：

niri validate

它会解析配置文件并列出所有错误——niri 出问题时界面也会提示你执行这条命令。

最小可用配置示例（其余全部走默认值）：

layout { gaps 4 } input { focus-follows-mouse }

进阶定制：布局、动画、快捷键 🎛

列宽与窗口大小

列宽不必手算。默认绑定了Mod+R / Mod+Shift+R循环预设列宽，Mod+= / Mod+-以 10% 步进调节列宽，Mod+Shift+= / Mod+Shift+-调窗口高度。想让某类应用常驻某一列宽，用window-rule按标题或类名匹配即可。

动画怎么调

所有动画都集中在animations {}区块，每项可以独立设成off，也可以在顶部写off一刀全关、写slowdown统一减速。默认值参考：窗口打开是 150ms 的ease-out-expo，窗口移动、切换工作区走弹簧（spring）曲线。嫌慢就加：

animations { slowdown 0.5 // 数值小于 1 是加速 }

绑定滚轮和鼠标

不只是键盘。滚动绑定会随natural-scroll设置自动换方向，cooldown-ms可限流：

binds { Mod+WheelScrollDown cooldown-ms=150 { focus-workspace-down; } Mod+WheelScrollUp cooldown-ms=150 { focus-workspace-up; } }

按下的绑定默认会重复触发，不想要就加repeat=false。忘了某个键的 XKB 名字时，用wev这类工具按一下就能看到。

窗口规则：圆角与边框

想给所有窗口加圆角，加一条窗口规则即可：

window-rule { geometry-corner-radius 12 clip-to-geometry true }

多屏、全屏与工作区

每台显示器有独立的窗口带，窗口绝不会"溢出"到相邻屏幕；拔掉显示器，它的工作区会迁移走，重新接上又迁回来。全屏与最大化的效果可参考官方文档截图：

输出配置按设备名写区块，同一块屏的分辨率、缩放、位置都能定死。需要"接了外接屏就换一套布局"这类联动逻辑，官方推荐搭配 Kanshi 工具实现，它通过 IPC 与 niri 通信，可在配置里用spawn-at-startup "/usr/bin/kanshi"拉起。三指手势在gestures {}区块配置，支持触摸板与鼠标滑动切列、切工作区。

高频问题排坑 🩹

配置报错、界面弹黑框？黑框提示的就是niri validate。按提示修到无错误为止；binds区块不会被自动补默认值，删掉它就等于没有快捷键，别误删。

透明窗口透出色带 / 想关掉应用自带的圆角边框（CSD）？在配置顶层启用prefer-no-csd再重启应用，niri 会请求窗口放弃自绘边框，焦点环也会改画在窗口外围。副作用是鼠标边缘拖拽 resize 消失，改用Mod+右键拖动调整。

NVIDIA 黑屏或显存占用高？需要较新的驱动（支持 GBM）并在内核启动参数加nvidia-drm.modeset=1；显存问题按官方 Nvidia 文档打补丁。混合显卡笔记本外接屏卡顿，可试debug区块的render-drm-device指定独显渲染，代价是更费电。

要跑 Steam、旧版 Discord 等 X11 应用？niri 从 25.08 起内置 xwayland-satellite 集成，按官方 Xwayland 页启用即可；Electron 应用大多加个启动参数就能原生跑 Wayland。

登录后有两条状态栏？装了桌面壳（自带一条 bar）而 niri 默认配置还会spawn-at-startup "waybar"，删掉这行（或先pkill waybar）即可。

锁屏死了留下红屏？红屏是 niri 的锁屏背景。切到别的 TTY 向WAYLAND_DISPLAY手动拉起 swaylock，或给锁屏绑定加allow-when-locked=true以便在红屏上直接再触发。

验证与日常维护 ✅

养成两个习惯就能省心：

1. 改完配置跑一次niri validate。热重载虽然友好，但解析失败时 niri 会弹错误通知并保留旧配置，提前验证更稳。
2. 升级时先看默认配置的 diff。官方承诺发布版本之间不破坏已有配置，binds除外——升级后扫一眼niri validate的输出即可。

想深入细节时，从仓库内这两处入手：官方文档（docs/wiki） 覆盖每个配置区块，配置解析模块 可以看到每个选项在代码里如何生效。

延伸阅读：Workspaces 页讲透工作区行为，Window-Rules 页列出全部窗口规则。

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