要写在前面的是关于niri对于x11的支持情况。实际上，niri的作者直接表明X11 is very cursed，所以niri暂时不会有内置的x11兼容方案，不同于Hyprlnd采用wlroots实现内置XWayland的解决方案，niri目前仅能通过第三方的软件支持运行XWayland，如xwayland-satellite、xwayland-run等 (下个版本niri将会内置xwayland-satellite，曲线救国了算是)，如果你的工作区离不开X11，或需要高性能的X11环境,niri可能不那么适合你😮‍💨

xwayland-satellite解决方案#

根据niri wiki介绍，首先通过你的包管理器下载xwayland-satellite

1
# Arch 需要启用extra存储库
2
sudo pacman -S xwayland-satellite

设置xwayland-satellite为自启动

1
spawn-at-startup "xwayland-satellite"

关于这里语句的意义，我们在接下来的内容将会介绍

配置显示环境变量首先运行一次xwayland-satellite，观察输出，找到显示序号Xwayland :n：

1
INFO  xwayland_satellite         > Connected to Xwayland on :2

接着将其写入配置文件

1
environment {
2
    DISPLAY ":2"
3
}

或者，你还可以使用xwayland-satellite :12来要求xwayland-satellite使用指定的DISPLAY number

配置#

niri 中 Input，Outputs，Key Bindings，Switch Events，Layout，Named Workspaces，Miscellaneous，Window Rules，Layer Rules，Animations，Gestures，Debug Options都支持在配置文件 ~/.config/niri/config.kdl 中更改

配置文件使用kdl (递归命名KDL Document Language)，这是一个比较小众的配置文件语言，它具有类似XML的节点语法，在这里，我们不深入讨论KDL的具体语法，实际上，如果你使用过XML、JSON等配置文件，你可以很快掌握kdl的基本语法

下面，我将介绍一些常用的配置，更具体的内容可以自行在wiki中查阅

开机启动#

1
spawn-at-startup "xwayland-satellite"
2
spawn-at-startup "qs" "-c" "dms"
3
spawn-at-startup "~/.config/niri/scripts/Polkit.sh"

设置软件开机自启，需要传参的用空格和引号分开，也可以给入一个文件位置来打开

Input#

查看折叠的代码

1
input {
2
    keyboard {
3
        repeat-delay 300
4
        repeat-rate 40
5

6
        numlock
7
    }
8

9
    touchpad {
10
        // off
11
        tap
12
        // dwt
13
        // drag false
14
        // drag-lock
15
        natural-scroll
16
        // accel-speed 0.2
17
        // accel-profile "flat"
18
        // scroll-method "two-finger"
19
    }
20

21
    mouse {
22
        // off
23
        // natural-scroll
24
        // accel-speed 0.2
25
        accel-profile "flat"
26
        // scroll-method "no-scroll"
27
    }
28

29
    // warp-mouse-to-focus
30

31
    // focus-follows-mouse max-scroll-amount="0%"
32
    workspace-auto-back-and-forth
33
}

Keyboard#

repeat-delay: 长按某个键多久后触发连点
repeat-rate：每秒多少个字符
numlock：开机时自动打开数字键

touchpad#

niri触控板支持三指左右滑动滚动窗口，三指上下滑动切换工作空间，四指快速滑动打开Overview（默认快捷键为Mod+O）

tap：点击功能
dwt：disable-when-typing，打字时禁用
drag：点击后拖动，值为true或false
drag-lock：拖动时放手保持拖动一段时间
natural-scroll：反转双指滚动方向，设置时才是符合直觉的滚动方式

mouse#

natural-scroll：同上，不设置时反而是符合直觉的滚动方式
accel-speed：速度
accel-profile：鼠标加速方案，值为adaptive表加速或 flat不加速

其他#

warp-mouse-to-focus：切换焦点窗口时移动鼠标，默认值为mode="center-xy"，如果切换焦点后光标不在窗口内就跳转光标到窗口中心，反之不移动。mode="center-xy-always"为始终跳转
focus-follows-mouse：使焦点自动根据光标位置切换，可以设置max-scroll-amount="n%"，设置后如果焦点跟随光标会导致视图滚动超过设定的量，则不会切换焦点
workspace-auto-back-and-forth：使用索引切换工作空间时，如果通过索引切换到当前工作空间，将会自动切换到上一个工作空间

Cursor#

1
cursor {
2
    xcursor-theme "Bibata-Modern-Ice"
3
    xcursor-size 24
4
}

设置光标主题和大小

Overview#

1
overview {
2
    backdrop-color "#282828"
3
    workspace-shadow {
4
        off
5
    }
6
}

设置Overview背景色

Layout#

查看折叠的代码

1
layout {
2
    gaps 8
3
    center-focused-column "never"
4

5
    preset-column-widths {
6
        proportion 0.2
7
        proportion 0.4
8
        proportion 0.6
9
        proportion 0.8
10
    }
11
    preset-window-heights {
12
        proportion 0.25
13
        proportion 0.5
14
        proportion 0.75
15
        proportion 1.0
16
    }
17

18
    default-column-width { proportion 0.5; }
19

20
    focus-ring {
21
        off
22
        width 4
23
        active-color "#7fc8ff"
24
        inactive-color "#505050"
25
        active-gradient from="#C65B82" to="#09157B" angle=135
26
        inactive-gradient from="#C65B82" to="#09157B" angle=135 relative-to="workspace-view"
27
    }
28

29
    border {
30
        // off
31
        width 4
32
        // active-color "#ffc87f"
33
        // inactive-color "#505050"
34
        urgent-color "#9b0000"
35
        active-gradient from="#C65B82" to="#09157B" angle=135 relative-to="workspace-view" in="oklch longer hue"
36
        inactive-gradient from="#505050" to="#808080" angle=45 relative-to="workspace-view"
37
    }
38

39
    shadow {
40
        //on
41
        softness 1
42
        spread 1
43
        offset x=0 y=5
44
        color "#0007"
45
    }
46

47
    struts {
48
        // left 64
49
        // right 64
50
        // top 64
51
        // bottom 64
52
    }
53
}

gaps：窗口之间的间隔
center-focused-column：控制窗口在显示器上居中的行为

- never：（默认值）不居中，当聚焦的列会显示屏幕的左边缘或右边缘。
- always：被聚焦的列将始终居中显示。
- on-overflow：当聚焦的列与之前聚焦的列无法同时显示在屏幕上时，会将该列居中显示。

column#

preset-window-widths 使用快捷键(默认是Mod+R)调整窗口时的宽度
preset-window-heights 使用快捷键(默认是Mod+Shift+R)调整窗口时的高度
default-column-width 打开新窗口时的默认宽度

值为proportion 0.66667 表对于的屏幕的占比，比如示例的2/3
或 fixed 1280 表固定的像素数

focus-ring、border#

focus-ring和border的区别在于：focus ring只围绕活动窗口绘制，而borders会围绕所有窗口绘制，并且会影响窗口的大小

width：显然是宽度，单位为像素，但是可以填入小数，在设置了缩放后会被计算
active-color：焦点窗口装饰的颜色
inactive-color：所有其他窗口装饰的颜色
active-gradient：active-color的渐变版
inactive-gradient：inactive-color的渐变版

- 渐变颜色可以添加relative-to="workspace-view"值表示全部窗口一起渐变，不设置则为各自渐变。同时它们支持类似css的渐变插值，你可以使用类似 in="srgb-linear" 或 in="oklch longer hue" 的语法来设置

所有的颜色支持以下的方式定义

- CSS 命名颜色：如 red
- RGB 十六进制：如 #rgb、#rgba、#rrggbb、#rrggbbaa
- CSS 类似表示法：如 rgb(255, 127, 0)、rgba()、hsl() 等几种格式。

窗口圆角#

看到这儿，你可能迫不及待的想要设置窗口圆角了，我就在这里提前告诉你，我们可以通过设置窗口规则来定义圆角：

1
window-rule {
2
    draw-border-with-background false
3
    geometry-corner-radius 12
4
    clip-to-geometry true
5
}
6

7
prefer-no-csd

通过不设置匹配来匹配全部的窗口
draw-border-with-background：border装饰窗口并不只是加一个边框，而是填充一个背景，如果你使用某个背景透明的软件就会发现，设置这项为false可以取消背景
geometry-corner-radius：圆角半径，也可以设置4个值来表示各个j角的圆角
clip-to-geometry：geometry-corner-radius只会设置focus-ring和border的圆角，这项参数将同时应用圆角至窗口
prefer-no-csd：有些软件可能自带窗口圆角和阴影，为了统一的效果，我们可以设置这项要求软件取消 client-side decorations

struts#

1
struts {
2
        left 64
3
        right 64
4
        top 64
5
        bottom 64
6
    }

设置窗口四边的空白，也可以设置为负值

Ranges

struct库

niri快速配置

https://blog.erina.top/posts/niri/

作者

Erina Yip

发布于

2025-08-29

许可协议

CC BY-NC-SA 4.0

xwayland-satellite解决方案