niri：一个用 Rust 编写的可滚动平铺 Wayland 合成器全面指南

niri：一个用 Rust 编写的可滚动平铺 Wayland 合成器全面指南

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

导读：niri 是一个从零为"可滚动平铺"（scrollable tiling）而构建的 Wayland 合成器，窗口在无限延伸的水平条带上按列排布，新窗口永远不会挤压已有窗口。本文以 niri 项目 README 为主体，结合仓库内的 wiki 文档 与源码，系统讲解其核心设计、功能特性、安装启动、配置体系与构建方式，帮助你快速上手并深入理解这一"滚动式"窗口管理的实际用法。

什么是 niri？

niri（读作 "niri"）是一个用 Rust 编写的 Wayland 合成器，其核心设计理念是可滚动平铺（scrollable tiling）。与传统的平铺窗口管理器把窗口塞进有限屏幕不同，niri 把窗口排列在一条无限向右延伸的条带上，通过滚动视口来查看不同位置的窗口。

这种布局方式带来了一个关键特性：打开新窗口永远不会导致已有窗口被挤压或改变尺寸。窗口只是排在新列上，视口滚动过去即可看到，工作流完全围绕"滚动"而非"缩放"展开。

niri 的设计灵感来自 [PaperWM]——一个运行在 GNOME Shell 之上的可滚动平铺扩展。项目作者在 README 中写道，之所以决定自己编写合成器，正是因为 PaperWM 作为 GNOME Shell 扩展，必须对抗 Shell 的全局窗口坐标系来阻止窗口溢出相邻显示器。而在 niri 中，多显示器隔离是从零设计的核心部分。

从源码结构看，niri 的主程序位于 src/，采用模块化组织：layout模块实现列、工作区与平铺逻辑，input模块处理键盘、触控板与手势，render_helpers负责着色器与渲染效果，ipc模块提供niri msg命令所需的进程间通信，niri-config与niri-ipc则是独立的配置解析与 IPC 库。仓库还包含完整的 视觉测试 与单元测试快照。

核心设计：无限条带、独立显示器与动态工作区

README 的 About 部分概括了 niri 三大核心设计，这些设计在 布局源码 与 Workspaces 文档 中有着具体体现。

列与无限条带

窗口在一条无限向右延伸的条带上按列排列。打开新窗口时，它会在当前列的右侧创建新列，已有窗口的尺寸与位置完全不受影响。当窗口超出屏幕范围时，可以通过滚动或聚焦操作把视口移动到目标列。

每台显示器拥有独立的窗口条带

每个显示器（monitor）都有自己独立的窗口条带，窗口永远不会"溢出"到相邻显示器。你可以在不同显示器上维护各自独立的列集合，互不干扰。

动态工作区

工作区是动态的，纵向排列：

• 每台显示器有一组独立的工作区；
• 显示器最底部始终存在一个空工作区；
• 当你在这个空工作区打开窗口时，它下方会立即出现一个新的空工作区；
• 中间的"空工作区"在切换离开后会自动消失；
• 工作区在显示器断开/重连时会被保留：断开时它们会移到另一台显示器，重连时自动移回原显示器。

工作区定位：按索引与按名称

niri 的focus-workspace 2、move-column-to-workspace 4等操作中的索引，指的是当前恰好位于聚焦显示器该位置的工作区，而不是一个固定编号。这与静态工作区系统有本质区别——工作区本身没有固定索引。

若需要"永久"的工作区，可以创建命名工作区，或使用set-workspace-name动作。命名工作区即使变空也不会消失，且可以按名称引用，例如focus-workspace "browser"。

示例工作流

作者在 Workspaces.md 中分享了自己的使用习惯：浏览器放在最上方工作区，每个项目或"事项"一个工作区；工作区内 1–2 个常切换的窗口，偶尔需要的临时窗口放在视口外；需要新的常驻窗口时放到新工作区，然后通过move-workspace-up/down把它移到浏览器下方，让一次focus-workspace-up/down就能到达目标。

功能特性总览

README 列出了 niri 的主要功能，下面结合 wiki 文档 逐一展开说明其实际用法。

从零构建的可滚动平铺

这是 niri 最核心的特性，如前所述，体现在列式布局、无限条带与独立显示器设计上。

类 GNOME 的动态工作区

见上文"动态工作区"一节，详细说明见 Workspaces.md。

Overview（总览视图）

niri 内置一个 Overview，将工作区与窗口缩小展示，方便快速定位与切换。相关配置位于顶层overview {}段（Configuration:-Miscellaneous.md）：

overview { zoom 0.5 backdrop-color "#262626" workspace-shadow { // off softness 40 spread 10 offset x=0 y=10 color "#00000050" } }

zoom取值范围 0–0.75，越小工作区缩得越小；backdrop-color设置工作区背后的底色；workspace-shadow控制总览中工作区后方的阴影，其参数与布局中的shadow一致。

内置截图 UI

niri 自带交互式截图界面，默认按键如下（详见 Getting-Started.md）：

截图保存路径可用顶层screenshot-path配置，支持strftime(3)时间格式化，设为null则只复制到剪贴板而不落盘：

screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"

屏幕录制：xdg-desktop-portal-gnome

niri 通过 xdg-desktop-portal-gnome 支持显示器与窗口级别的屏幕录制，并提供了两个特色能力：

• block-out-from屏蔽敏感窗口：通过窗口规则把密码管理器、聊天窗口等从录制中屏蔽为纯黑矩形；
• 动态录制目标：录制目标可以在运行中切换所显示的内容。

// 从屏幕录制中屏蔽密码管理器。 window-rule { match app-id=r#"^org\.keepassxc\.KeePassXC$"# match app-id=r#"^org\.gnome\.World\.Secrets$"# block-out-from "screencast" }

需要说明的是，block-out-from "screencast"只对 xdg-desktop-portal 的录制生效，第三方截图工具仍可能拍到这些窗口；若要彻底屏蔽，应使用block-out-from "screen-capture"，它会同时屏蔽自动截图动作（内置交互式截图 UI 仍可使用）。

触控板与鼠标手势

niri 支持触控板手势（如三指滑动切换工作区）与鼠标手势，相关配置见 Gestures.md 与 Configuration:-Gestures.md。底层实现位于 input/scroll_swipe_gesture.rs 等输入模块。

窗口标签页（Tabs）

可以把多个窗口分组进同一列并切换显示，形成类似浏览器标签页的体验。相关文档见 Tabs.md，布局中的default-column-display可以设置新列的默认显示模式：

// 让所有新列默认以标签页模式显示。 layout { default-column-display "tabbed" tab-indicator { hide-when-single-tab } }

可配置布局：间隙、边框、struts、窗口尺寸

布局配置集中在layout {}段（Configuration:-Layout.md），一个典型配置如下：

layout { gaps 16 center-focused-column "never" always-center-single-column empty-workspace-above-first default-column-display "tabbed" background-color "#003300" preset-column-widths { proportion 0.33333 proportion 0.5 proportion 0.66667 } default-column-width { proportion 0.5; } preset-window-heights { proportion 0.33333 proportion 0.5 proportion 0.66667 } focus-ring { on width 4 active-color "#7fc8ff" inactive-color "#505050" urgent-color "#9b0000" } border { off width 4 active-color "#ffc87f" inactive-color "#505050" urgent-color "#9b0000" } shadow { off softness 30 spread 5 offset x=0 y=5 draw-behind-window true color "#00000070" } struts { // left 64 // right 64 // top 64 // bottom 64 } }

各选项要点：

• gaps：窗口内外的间隙（逻辑像素），支持小数，会按各显示器缩放因子取整到物理像素；
• center-focused-column：切换焦点时何时居中列，可选"never"（默认，靠边）、"always"（始终居中）、"on-overflow"（放不下时居中）；
• always-center-single-column：工作区只有单列时始终居中；
• empty-workspace-above-first：除末尾外，在最上方也保持一个空工作区；
• preset-column-widths/preset-window-heights：switch-preset-column-width（Mod+R）与switch-preset-window-height（Mod+Ctrl+Shift+R）循环切换的尺寸档位，proportion为输出宽度的比例（已计入间隙），fixed为精确的逻辑像素；
• default-column-width：新窗口的默认宽度，空括号{}表示由窗口自己决定初始宽度；
• struts：收缩窗口占用区域（类似外层间隙），支持负值，可用负 struts 配合gaps模拟"仅内间隙"效果。

焦点环（focus-ring）与边框（border）

两者的区别：焦点环只画在活动窗口周围，边框画在（几乎）所有窗口周围；边框会占用窗口尺寸（窗口缩小为其让位），焦点环则不会。

颜色支持多种写法：CSS 命名色（"red"）、十六进制（"#rgb"、"#rrggbbaa"等）、CSS 函数式（rgb(255, 127, 0)、hsl()等）。还支持渐变：

layout { border { active-gradient from="#ffbb66" to="#ffc880" angle=45 relative-to="workspace-view" } }

渐变渲染与 CSSlinear-gradient一致，angle默认 180（自上而下）；relative-to="workspace-view"让渐变跨整个工作区视口而非单个窗口；in="..."可指定插值颜色空间，支持srgb（默认）、srgb-linear、oklab、oklch（可配shorter/longer/increasing/decreasing hue）。

一个细节：默认情况下焦点环/边框是画在窗口背后的实色矩形，因此会透过半透明窗口显示出来（因为 CSD 窗口形状任意）。如果不喜欢，可以启用顶层prefer-no-csd，niri 会对同意去掉 CSD 的窗口把焦点环/边框画在窗口周围；也可用draw-border-with-background窗口规则按窗口覆盖。

阴影（shadow）

shadow选项支持softness（模糊半径）、spread（扩展量，25.05 起可为负）、offset（偏移）、color（颜色与透明度）、draw-behind-window（画在窗口背后以规避 CSD 圆角伪影）、inactive-color。阴影绘制会跟随geometry-corner-radius窗口规则设置的圆角。

支持 Oklab / Oklch 的渐变边框

如上所述，渐变边框不仅支持普通 sRGB 插值，还支持Oklab 与 Oklch颜色空间。从源码看，niri-visual-tests 中包含 gradient_oklab.rs、gradient_oklch_longer.rs 等一系列针对这些颜色空间的渲染测试用例，用于验证不同插值模式（shorter/longer/increasing/decreasing hue）与 alpha 通道的渲染结果。

窗口与 layer-shell 表面的背景模糊

niri 支持为窗口和 layer-shell 表面启用背景模糊（Window-Effects.md），并有高效的 xray 模糊模式。全局模糊参数在顶层blur {}段配置：

// 默认值如下： blur { // off passes 3 offset 3 noise 0.02 saturation 1.5 }

• passes：双 Kawase 模糊的下采样/上采样次数，越多越平滑但越耗 GPU；
• offset：每遍的像素偏移倍数，1是原始双 Kawase 模糊，调大更平滑且不增加 GPU 开销，但过大会出现伪影（此时需增加passes）；
• noise：叠加噪点以减轻色带；
• saturation：背景饱和度，大于 1 增强、小于 1 减弱；
• off：关闭全部模糊（包括窗口主动请求的）。

窗口规则中的background-effect可按窗口覆盖 xray/blur/noise/saturation。注意非 xray 模糊目前是实验特性，窗口打开/关闭动画期间不生效。

支持自定义着色器的动画

niri 内置弹簧/贝塞尔动画（src/animation/），并支持为窗口打开、关闭、调整大小等动画挂载自定义着色器。仓库中 src/render_helpers/shaders/ 提供了一组现成的 GLSL 着色器模板（如close_prelude.frag、open_epilogue.frag、resize.frag、gradient_fade.frag等），docs/wiki/examples/ 里还有可直接参考的close_custom_shader.frag、open_custom_shader.frag、resize_custom_shader.frag示例。

配置热重载

niri 的配置是实时重载的：编辑并保存配置文件，键位绑定、输出模式、窗口规则等所有变更会立即生效，无需重启。详见下文"配置体系"。

屏幕阅读器支持

niri 支持无障碍屏幕阅读器，相关说明见 Accessibility.md，DBus 实现位于 src/dbus/freedesktop_a11y.rs。

状态与常见问题（FAQ 式要点）

README 的 Status 部分回答了社区最关心的几个问题：

README 强调：niri 本身并不是一个完整的桌面环境。它稳定到可以日常使用，但需要搭配桌面外壳（如 [DankMaterialShell] 或 [Noctalia]）或传统组件（状态栏、启动器、通知守护进程等）才能构成完整桌面，相关软件清单见 Important-Software.md。

安装与启动

快速开始

README 推荐的快速上手方式是安装发行版软件包并搭配 DankMaterialShell：

Fedora：

sudo dnf copr enable avengemedia/dms sudo dnf install niri dms systemctl --user add-wants niri.service 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 systemctl --user add-wants niri.service dms

Ubuntu 25.10+：

sudo add-apt-repository ppa:avengemedia/danklinux sudo add-apt-repository ppa:avengemedia/dms sudo apt install niri dms

安装后注销，在显示管理器中选择 Niri登录；若不使用显示管理器，则在 TTY 上运行niri-session。

注意：默认 niri 配置会启动 Waybar，如果同时使用 DMS 的栏可能会出现两个栏，可用pkill waybar停掉，并删除~/.config/niri/config.kdl中的spawn-at-startup "waybar"一行。

其他发行版软件包还包括 Fedora COPR、NixOS Flake 等；Debian 系还有 pacstall 包。完整的打包说明见 Packaging-niri.md。

从 TTY 启动与嵌套窗口

• 无显示管理器时，从 TTY 运行niri-session（systemd/dinit）或niri --session（其他）。--session会把环境变量全局导入系统管理器与 D-Bus 并启动 D-Bus 服务；niri-session还会把 niri 作为 systemd/dinit 服务启动，拉起图形会话 target（portal 等服务需要）。
• 也可以直接在已有桌面会话里运行niri，它会以窗口形式打开。注意窗口模式主要面向开发调试，略有瑕疵（尤其是热键）。

常见启动问题

• NVIDIA 黑屏：先更新驱动（需支持 GBM 的较新 GPU/驱动），并确保内核开启 modeset（通常在内核命令行加nvidia-drm.modeset=1）。
• Asahi/ARM/kmsro 设备黑屏：可能是主渲染设备检测错误。查看/dev/dri/下的设备，然后在配置中手动指定：

debug { render-drm-device "/dev/dri/renderD128" }

• NixOS：注意系统 mesa 与 niri 的 mesa 版本需一致，否则 TTY 启动可能黑屏；Intel 显卡可能需要额外 workaround。
• 虚拟机：务必开启 3D 加速。

默认热键速查

在 TTY 上运行时，Mod 键是Super；在嵌套窗口运行时是Alt。总体规律：某个热键负责"切换焦点到某处"，那么加上Ctrl就变成"把焦点窗口/列移动到某处"。

完整热键与动作说明见 Configuration:-Key-Bindings.md。

配置体系

配置文件位置与加载

niri 会按顺序查找$XDG_CONFIG_HOME/niri/config.kdl（即通常的~/.config/niri/config.kdl），回退到/etc/niri/config.kdl。若两者都不存在，niri 会创建用户配置并把默认配置文件（构建时嵌入二进制）写进去。建议以默认配置为起点修改。

• 配置实时重载：保存即生效，无需重启；
• 运行niri validate可解析配置并查看错误；
• 用--config/-c参数或环境变量$NIRI_CONFIG指定其他路径；--config优先级更高；路径无效则不加载配置。

语法：KDL

配置使用 KDL 格式编写：

• //开头是注释；
• /-放在节点前可整段注释掉；

/-output "eDP-1" { off }

• 开关型选项是"标志"（flag）：写出即启用，省略或注释即禁用：

input { focus-follows-mouse // 启用 // focus-follows-mouse // 禁用 }

• 大部分段不可重复，例外如按设备名区分的段（output "eDP-1" {}、output "HDMI-A-1" {}合法，但同名输出重复出现不合法）；
• 省略大部分段会使用默认值，但binds {}不会自动填充默认值，务必保留该段。

配置段索引

Configuration:-Introduction.md 按段列出了各专题文档：

• input {}——键盘、鼠标、触控板、数位板等输入设备；
• output "eDP-1" {}——输出模式、缩放、变换、位置；
• binds {}——键位绑定与动作；
• switch-events {}；
• layout {}——布局与窗口外观；
• 顶层选项——spawn-at-startup、prefer-no-csd、cursor、overview等；
• window-rule {}——按窗口匹配的规则；
• layer-rule {}——layer-shell 表面规则；
• animations {}；
• gestures {}；
• recent-windows {}；
• debug {}；
• include "other.kdl"——引入其他配置文件。

破坏性变更政策

niri 遵循一条原则：正式发布版本不应破坏已有配置文件（例如 v0.1.0 的默认配置在 v25.02 上仍可解析）。例外仅限解析 bug 的修复（如曾经允许多个键绑定同一按键，后改为解析失败）。该政策只对正式发布生效，发布之间的 git 提交可能临时破坏配置。

深入：窗口规则（window-rule）

窗口规则是 niri 精细控制单个窗口行为的主要手段，按配置文件中的出现顺序处理，支持match与exclude指令：窗口需匹配任一match且不匹配任何exclude才应用该规则。

// 先给所有窗口设置 open-maximized=true…… window-rule { open-maximized true } // ……再对 Alacritty 覆盖回 false。 window-rule { match app-id="Alacritty" open-maximized false }

常用匹配器包括：title/app-id（正则，任意位置匹配）、is-active、is-focused、is-active-in-column、is-floating、is-window-cast-target、is-urgent、at-startup（启动后前 60 秒）。正则建议使用 KDL 原始字符串，如match app-id=r#"^org\.telegram\.desktop$"#。

窗口属性分为两类：

• 开窗时生效（应用于初始 configure 请求）：default-column-width、default-window-height、open-on-output、open-on-workspace、open-maximized、open-maximized-to-edges、open-fullscreen、open-floating、open-focused；
• 持续生效：block-out-from、opacity、variable-refresh-rate、default-column-display、default-floating-position、scroll-factor、draw-border-with-background、focus-ring/border/shadow/tab-indicator覆盖、geometry-corner-radius、clip-to-geometry、tiled-state、background-effect、popups，以及min-width/max-width/min-height/max-height尺寸约束。

一个实用的组合示例——为 Firefox 画中画窗口设置浮动、固定尺寸并停靠屏幕左下角：

window-rule { match app-id="firefox$" title="^Picture-in-Picture$" open-floating true default-column-width { fixed 480; } default-window-height { fixed 270; } default-floating-position x=32 y=32 relative-to="bottom-left" }

default-floating-position的坐标相对于工作区，relative-to支持top-left、top-right、bottom-left、bottom-right、top、bottom、left、right，坐标方向随基准变化（如bottom-left时y向上为正）。

查看窗口的 title/app-id 可运行niri msg pick-window后点击目标窗口。

键位绑定与动作

binds {}段中每个绑定由热键加花括号动作构成：

binds { Mod+Left { focus-column-left; } Super+Alt+L { spawn "swaylock"; } }

热键由+连接的修饰键加末尾的 XKB 键名组成。合法修饰键：Ctrl/Control、Shift、Alt、Super/Win、ISO_Level3_Shift/Mod5（AltGr）、ISO_Level5_Shift，以及特殊的Mod（TTY 下等于 Super，嵌套窗口下等于 Alt；自 25.05 起可在input段自定义）。查找键名可用wev等工具。

绑定还支持：

• repeat=false关闭按住连发（默认连发）；
• cooldown-ms=500限流，防止过快重复触发（常用于滚轮绑定）；
• 滚动绑定：Mod+WheelScrollDown/Up/Left/Right与Mod+TouchpadScrollDown/Up，会随natural-scroll改变方向，且按住修饰键时滚动事件会被 niri 消费、不再传给应用；
• 鼠标点击绑定（25.01+）：Mod+MouseLeft等，作用于点击时聚焦的窗口（而非被点击的窗口）；绑定Mod+MouseLeft/Right会覆盖对应的移动/调整大小手势；
• 热键总览自定义（hotkey-overlay-title）：给绑定设置标题以显示在"重要热键"列表中，或设为null隐藏硬编码绑定；标题支持 Pango markup。

关于spawn动作：niri 不用 shell 执行命令，参数必须逐项分开；需要变量/管道/~展开时用spawn-sh（25.08+，等价于spawn "sh" "-c" ...）或手动包一层sh -c。唯一的特例是程序名开头的~会被展开。

每个动作都可通过niri msg action以编程方式调用（如niri msg action do-screen-transition触发主题切换的屏幕过渡动画），运行niri msg action可列出全部动作。

构建 niri

从源码构建

1. 安装依赖（Ubuntu 24.04 示例）：

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 对应包为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。

2. 安装最新稳定版 Rust（https://rustup.rs/）；
3. 构建：

cargo build --release

特性列表见 Cargo.toml。例如用 dinit 替代 systemd：

cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast

警告：不要用--all-features构建！部分特性仅用于开发（例如某个特性会开启无上限增长的内存 profiling 缓冲区）。

NixOS / Nix

社区维护的 flake 提供带全部依赖的 devshell，用nix build构建后运行./results/bin/niri；非 NixOS 可能需要 NixGL：

nix run --impure github:guibou/nixGL -- ./results/bin/niri

手动安装文件位置

不通过包管理器安装时，建议按以下位置放置文件（需确保niri.service中的 niri 路径正确，默认/usr/bin/niri）：

这些资源文件在仓库中均可找到：resources/niri-session、resources/niri.desktop、resources/niri-portals.conf、resources/niri.service等。

生态与周边

• 桌面外壳：niri 本身不是完整桌面环境，可搭配 DankMaterialShell、Noctalia 等 Quickshell 外壳，或 LXQt（官方支持 niri）、XFCE 组件、COSMIC 会话（通过cosmic-ext-extra-sessions）；
• 社区资源：awesome-niri 汇总了 niri 相关的链接与项目；主沟通渠道是 Matrix 频道，另有社区 Discord；
• 同类项目：README 列举了其他实现类似工作流的项目——[PaperWM]（GNOME Shell）、[karousel]（KDE）、scroll 与 papersway（sway/i3）、Hyprland 内置的 scrolling layout、Paneru 与 PaperWM.spoon（macOS）；
• 贡献：无论编程还是非编程方式都欢迎，概览见 CONTRIBUTING.md。

小结

niri 用"无限条带 + 独立显示器 + 动态纵向工作区"的组合重新定义了平铺窗口管理的交互模型，在保留传统平铺（列内纵向堆叠、浮动窗口、标签页、工作区）的实用功能的同时，用滚动取代了挤压。它提供了热重载的 KDL 配置、可编程的窗口规则、内置截图与录制屏蔽、渐变边框/阴影/模糊等丰富的视觉效果，并且从底层支持多显示器、混合 DPI 与分数缩放。无论你是想尝试一种全新的窗口管理方式，还是想研究一个现代 Rust Wayland 合成器的完整实现，niri 都是一个值得深入的项目。

继续阅读：Getting-Started.md 与配置入门 是两条最合适的后续路线，README.md 中的各功能链接则指向全部专题文档。

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