niri 可滚动平铺 Wayland 合成器配置实操指南：5 分钟装好并定制你的第一套桌面

niri 可滚动平铺 Wayland 合成器配置实操指南：5 分钟装好并定制你的第一套桌面

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

niri 是一款可滚动平铺（scrollable-tiling）的 Wayland 合成器：窗口按列排布在可无限横向滚动的条带上，打开新窗口不会挤压已有窗口。本文面向刚接触 niri 的 Linux 用户：装好、写出第一份 config.kdl、排掉常见坑。

一分钟认识它：niri 是什么、适合谁

• 它是什么：用 Rust 编写的 Wayland 合成器，窗口以"列"为单位横向排列，鼠标滚轮或触摸板就能左右滚动；工作区在垂直方向动态生成。
• 适合谁：喜欢键盘驱动 + 手势操作、受够了"开一个窗口所有窗口跟着缩放"的人。
• 核心卖点：每块显示器有独立的窗口条带，窗口绝不会溢出到相邻屏幕；配置热重载，保存即生效。

特性	一句话说明
可滚动平铺	窗口按列排布，横向无限滚动
动态工作区	垂直排布，底部永远有一个空工作区
配置热重载	保存文件即应用，无需重启合成器
多显示器	每块屏幕独立窗口条带，混合 DPI 可用
内置截图	PrtSc 直接框选截图，Alt+PrtSc 截当前窗口

最短路径跑起来：各发行版的 niri 安装命令

这一节的目标只有一件事：让 niri 会话出现在你屏幕上。以下都是发行版现成软件包，按你的系统选一行执行即可。

系统	命令
Fedora	sudo dnf copr enable avengemedia/dms然后sudo dnf install niri dms
Arch Linux	sudo pacman -Syu niri xwayland-satellite xdg-desktop-portal-gnome xdg-desktop-portal-gtk alacritty dms-shell-niri matugen cava qt6-multimedia-ffmpeg
Ubuntu 25.10 及以上	sudo add-apt-repository ppa:avengemedia/danklinux，再sudo add-apt-repository ppa:avengemedia/dms，最后sudo apt install niri dms

装完后（Fedora 和 Arch）执行一次systemctl --user add-wants niri.service dms，登录时才会自动拉起会话。接着注销，在显示管理器里选 Niri 重新登录；不用显示管理器的话，直接在 TTY 里运行niri-session。验证方法：用 Mod+T（Mod 即 Super 键）打开终端，运行niri msg outputs，能看到你的屏幕列表，说明会话和 IPC 都正常。

第一份配置文件：写出并校验 config.kdl

这一节的目标：把自动生成的默认配置换成你自己的最小版本。文件在~/.config/niri/config.kdl（不存在时 niri 首次启动会自动生成一份）。格式是 KDL：//开头是注释，在节点前写/-可以整段注释掉。

有一点要注意：binds段不会自动填充默认值，自己写配置时别把这一段删了，否则所有快捷键全部失效。

input { touchpad { tap natural-scroll } } layout { gaps 16 } binds { Mod+T { spawn "alacritty"; } Mod+Q { close-window; } Mod+Shift+E { quit; } }

参数	说明
tap	开关型标志：触摸板单指点按算左键点击，写了就启用，注释掉就关闭
natural-scroll	自然滚动，滚动方向跟手指动作一致
gaps 16	窗口之间的间隙，单位是逻辑像素
Mod+T	Mod 在 TTY 下等于 Super，在嵌套窗口模式下等于 Alt
spawn "alacritty"	spawn 不走 shell，每个参数必须单独加引号
quit	退出前弹确认框，防止误触

保存后配置会热重载。想确认有没有写坏，在终端运行niri validate：有解析错误会直接打出来，无输出即通过。再按 Mod+T 试试新绑定的终端快捷键。

高频进阶场景：多屏、布局、动画与快捷键配置

多屏摆放：一个 output 段配好

目标：固定两块屏幕的位置和模式，让光标在屏间正常移动。

output "eDP-1" { scale 2 } output "HDMI-A-1" { mode "1920x1080@60.000" position x=1920 y=0 }

屏幕名用niri msg outputs查，写错名字整段都不生效。mode 里的刷新率必须和小数点后三位完全一致。position 按逻辑像素计算，要算上 scale。

效果：每块屏各自一条窗口条带；光标只能穿过直接相邻的屏幕边界，摆放顺序和物理位置对齐。

布局间隙与焦点环：layout 段调整

目标：加宽窗口间隙，换一个醒目的焦点环。

layout { gaps 24 center-focused-column "on-overflow" focus-ring { width 4 active-color "#7fc8ff" } }

gaps控制窗口间距；center-focused-column控制聚焦列是否在放不下时自动居中，可选never、always、on-overflow。focus-ring 的 width 是环向外扩展的像素数，颜色支持 CSS 写法，还能用渐变。

效果：切到屏外的列时自动居中显示，当前窗口被一圈蓝色描边标出。

动画手感：自定义窗口打开动画

目标：让窗口开合的节奏慢一点、顺一点。

animations { window-open { duration-ms 200 curve "ease-out-expo" } window-close { duration-ms 150 curve "ease-out-quad" } }

缓动型动画只有两个参数：duration-ms是时长，curve从ease-out-quad、ease-out-cubic、ease-out-expo等里选。想要带惯性的回弹感，就改用spring，配合 damping-ratio 等参数试调。

效果：窗口展开花 200 毫秒且末端减速，不再"啪"地弹出来。

快捷键绑定：给 binds 加自己的键

目标：绑一个音量面板，再让键盘物理静音键在锁屏时也能用。

binds { Mod+P repeat=false { spawn "pavucontrol"; } XF86AudioMute allow-when-locked=true { spawn-sh "wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle"; } }

repeat=false让按住不连续触发；allow-when-locked=true使快捷键在锁屏时依然有效；spawn-sh把整条命令作为单个参数交给sh -c，支持变量展开和管道。找不到某个键的 XKB 名字时，用wev工具按一下该键即可看到名字。

效果：Mod+P 一键打开音量面板，键盘的静音键锁屏后照样工作。

出问题先查这里：niri 常见问题速查

现象	最可能原因	一步修复
启动后出现两条任务栏	默认配置自带 waybar，和 DMS 自带的栏重复	pkill waybar，并删掉配置里的spawn-at-startup "waybar"行
改了配置却不生效	KDL 语法错误，整个文件未被重新加载	终端运行niri validate定位解析错误
output 段完全不生效	屏幕名和真实名称对不上	用niri msg outputs查真实名字
高刷新率没打上	mode 的刷新率没有和小数点后三位完全一致	照抄niri msg outputs里列出的 mode
NVIDIA 显卡 TTY 启动黑屏	驱动过旧不支持 GBM，或未开内核 modeset	按 docs/wiki/Nvidia.md 修驱动，或在内核参数加nvidia-drm.modeset=1

下一步：niri 官方文档与资源入口

• 想查全部配置项：从 docs/wiki/Configuration:-Introduction.md 入手，input、layout、window-rule、animations 等每个段都有独立页面，里面含完整参数说明和示例。
• 日常使用离不开的通知守护进程、portal 等软件清单见 docs/wiki/Important-Software.md；要跑 X11 应用（Steam、Discord 等）看 docs/wiki/Xwayland.md。
• 配置改乱了想回退，对照内置的默认配置 resources/default-config.kdl 逐项核对；更细的疑难杂症先翻 docs/wiki/FAQ.md。

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