niri 配置详解Miscellaneous 顶层选项完整指南启动命令、截图路径、光标、概览、X11 与模糊【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri本文系统讲解 niri一个可滚动的平铺式 Wayland 合成器配置文件中所有未单独成章的顶层选项从spawn-at-startup/spawn-sh-at-startup启动命令、prefer-no-csd装饰协商、screenshot-path截图路径到environment、cursor、overview、xwayland-satellite、clipboard、hotkey-overlay、config-notification与全局blur设置。读完本文你将能独立编写一份完整的 niri 顶层配置并理解每个选项在 niri 源码中的实现方式与生效时机。选项一览下面这段 KDL 代码汇总了所有杂项顶层选项及其典型写法//后为注释spawn-at-startup waybar spawn-at-startup alacritty spawn-sh-at-startup qs -c ~/source/qs/MyAwesomeShell prefer-no-csd screenshot-path ~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png environment { QT_QPA_PLATFORM wayland DISPLAY null } cursor { xcursor-theme breeze_cursors xcursor-size 48 hide-when-typing hide-after-inactive-ms 1000 } overview { zoom 0.5 backdrop-color #262626 workspace-shadow { // off softness 40 spread 10 offset x0 y10 color #00000050 } } xwayland-satellite { // off path xwayland-satellite } clipboard { disable-primary } hotkey-overlay { skip-at-startup hide-not-bound } config-notification { disable-failed } blur { // off passes 3 offset 3.0 noise 0.02 saturation 1.5 }这些选项在配置解析器中对应的数据结构定义在 niri-config/src/misc.rs 与 niri-config/src/lib.rs其中Config结构体见 niri-config/src/lib.rs集中声明了spawn_at_startup、prefer_no_csd、cursor、screenshot_path、clipboard、hotkey_overlay、config_notification、blur、overview、environment、xwayland_satellite等字段是理解每个选项作用域的最佳入口。spawn-at-startup启动时拉起进程spawn-at-startup用于在 niri 启动时启动程序第一个参数是程序二进制路径其后依次是传给程序的参数spawn-at-startup waybar spawn-at-startup alacritty spawn-at-startup alacritty -e fish该选项与spawn键绑定动作 行为一致细节可参考那里的完整说明。从源码看它属于多段multipart节点在 niri-config/src/lib.rs 中通过m_push!(spawn_at_startup)收集因此你可以在配置中多次书写每一条都会在启动时被执行。其参数结构为command: VecString见 niri-config/src/misc.rs。在合成器启动流程中src/main.rs 会先把这些命令从配置中取出随后在 src/main.rs 统一调用spawn()/spawn_sh()执行for elem in spawn_at_startup { spawn(elem.command, None); } for elem in spawn_sh_at_startup { spawn_sh(elem.command, None); }如果你以 systemd 会话方式运行 niri则开箱即用地支持 xdg-desktop-autostart——在 GNOME 里配置过自启动的应用在 niri 中也会直接生效通常无需再手工写spawn-at-startup。spawn-sh-at-startup启动时执行 shell 命令自 25.08 版本可用。spawn-sh-at-startup接受一个字符串参数原样交给sh执行因此可以使用 shell 变量、管道、~展开等一切 shell 特性// 所有参数都写在同一个字符串里。 spawn-sh-at-startup qs -c ~/source/qs/MyAwesomeShell其参数在 niri-config/src/misc.rs 中定义为单个command: String详细语义参见spawn-sh键绑定动作。prefer-no-csd请求应用省略客户端装饰prefer-no-csd是一个标志设置后 niri 会请求应用省略其客户端侧装饰CSD。如果某个应用明确请求 CSD该请求仍会被尊重同时客户端会被告知它们处于平铺状态从而去掉一些圆角设置prefer-no-csd后通过 xdg-decoration 协议协商服务端装饰SSD的应用其焦点环和边框会直接绘制在窗口内容周围而不会带有纯色背景。[!NOTE] 与大多数选项不同修改prefer-no-csd不会完全影响已经在运行的应用它会让部分窗口变成长方形但不会移除标题栏。这主要是因为 niri 需要绕开一个 SDL2 的 bug——该 bug 会阻止 SDL2 应用启动。 修改配置中的prefer-no-csd后请重启相关应用以完整生效。prefer-no-csd从源码看该标志通过 src/utils/mod.rs 的update_tiled_state()影响窗口状态它决定是否向窗口设置TiledLeft/TiledRight/TiledTop/TiledBottom状态位对不支持 xdg-decoration 的 GTK 应用尤其有用并在 src/niri.rs 中决定是否暴露装饰相关全局对象。新建/更新窗口时都会读取该值见 src/niri.rs 与 src/handlers/xdg_shell.rs。需要注意的是它同时控制客户端是否看得到装饰全局与平铺状态两件事这正是它在运行中无法完整即时生效的原因详见 src/utils/mod.rs 中的注释说明。screenshot-path截图保存路径设置截图保存路径开头的~会展开为用户主目录。路径会经过strftime(3)格式化以嵌入日期时间且 niri 会自动创建路径中不存在的最后一个文件夹screenshot-path ~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png也可以设为null以禁用保存截图到磁盘screenshot-path null默认值为~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png见 niri-config/src/misc.rs。底层实现位于 src/utils/mod.rs 的make_screenshot_path()它调用 libc 的strftime进行时间格式化并通过expand_home()展开~值为null时直接返回None从而跳过落盘。实际截图入口在 src/niri.rs 与 src/niri.rs。environment为子进程覆盖环境变量environment块用于覆盖 niri 派生进程的环境变量environment { // 像这样设置一个变量 // QT_QPA_PLATFORM wayland // 用 null 作为值来移除一个变量 // DISPLAY null }注意这些变量不会传播到 systemd 全局环境因此由 systemd 启动的工具和应用看不到它们。特别是如果你通过 systemd 启动桌面外壳如 DankMaterialShell再使用其内置的应用启动器应用将看不到这些环境变量。如果希望所有进程都能看到这些变量可以在登录 shell 配置如~/.bash_profile中设置。niri-sessionshell 脚本会经由登录 shell 运行并在启动 niri 之前把所有环境变量导入 systemd。注意在登录 shell 中设置的变量对所有合成器都可见而不仅是 niri。在实现上environment被解析为VecEnvironmentVariable见 niri-config/src/misc.rs并在 src/main.rs 中存入全局CHILD_ENV供 niri 派生出的所有子进程使用。cursor光标主题与尺寸设置光标的主题、尺寸同时也会设置XCURSOR_THEME与XCURSOR_SIZE环境变量cursor { xcursor-theme breeze_cursors xcursor-size 48 }默认值为xcursor-theme default、xcursor-size 24见 niri-config/src/misc.rsxcursor-size的类型为u80–255。hide-when-typing打字时隐藏光标自 0.1.10 版本可用。设置后按下键盘按键时隐藏光标cursor { hide-when-typing }[!NOTE] 该设置可能干扰 Wine 中以原生 Wayland 模式运行并使用鼠标视角mouselook的游戏如第一人称游戏。如果按按键的同时移动鼠标、视角会向下跳请尝试关闭此设置。hide-after-inactive-ms空闲后自动隐藏自 0.1.10 版本可用。设置后光标会在最后一次移动经过指定毫秒数后自动隐藏cursor { // 空闲一秒后隐藏光标。 hide-after-inactive-ms 1000 }对应字段hide_after_inactive_ms: Optionu32见 niri-config/src/misc.rs不设置即为null/永不自动隐藏。overview总览视图设置自 25.05 版本可用。Overview 是工作区与窗口的缩小总览视图用于快速查看全局、导航与拖拽窗口可通过toggle-overview键绑定、左上角热角或触摸板四指上滑打开详见 Overview。overview块即为其相关设置默认值为zoom 0.5、默认背景色与默认工作区阴影见 niri-config/src/misc.rs。zoom总览缩放比例控制总览中工作区缩小多少。zoom取值范围为 0 到 0.75值越小所有内容显得越小// 让总览中的工作区缩小为正常的四分之一。 overview { zoom 0.25 }解析时zoom被限定在FloatOrInt0, 1区间见 niri-config/src/misc.rs不过文档约定其有效范围为 0–0.75。backdrop-color工作区背景色设置总览中工作区背后的背景色该背景在切换工作区时也会显示在工作区之间。此颜色的 alpha 通道会被忽略// 让背景变亮。 overview { backdrop-color #777777 }也可以在输出output配置中按输出单独设置backdrop-color。workspace-shadow工作区阴影控制总览中工作区背后的阴影。这里的设置与布局layout部分中的普通shadow配置 一一对应详细说明请参考该文档。工作区阴影按高度归一化为 1080 像素的工作区尺寸进行配置随后随工作区一起缩放。实际使用中相比窗口阴影你需要更大的spread、offset和softness// 关闭总览中的工作区阴影。 overview { workspace-shadow { off } }xwayland-satellite与 xwayland-satellite 集成自 25.08 版本可用。设置与 xwayland-satellite 的集成。当检测到足够新版本的 xwayland-satellite 时niri 会创建 X11 socket、设置DISPLAY并在有 X11 客户端尝试连接时自动拉起xwayland-satellite如果 Xwayland 进程退出niri 会持续监听 X11 socket 并按需重启 xwayland-satellite——这与其它合成器内置 Xwayland 的工作方式非常相似。off禁用集成niri 不创建 X11 socket也不设置DISPLAY环境变量path设置xwayland-satellite二进制路径默认为xwayland-satellite按普通非绝对程序名查找。// 使用自定义构建的 xwayland-satellite。 xwayland-satellite { path ~/source/rs/xwayland-satellite/target/release/xwayland-satellite }对应结构体与默认值在 niri-config/src/misc.rs集成逻辑在启动流程中通过 src/main.rs 的xwayland::satellite::setup()完成成功时设置DISPLAY并记录 socket 名称否则移除DISPLAY以避免子进程连到宿主机 X11。clipboard剪贴板设置自 25.02 版本可用。设置disable-primary标志以禁用主剪贴板中键粘贴。切换该标志只对之后启动的应用生效clipboard { disable-primary }hotkey-overlay快捷键总览浮层设置Important Hotkeys重要快捷键浮层的相关设置可用toggle-hotkey-overlay键绑定开关。skip-at-startup启动时不显示如果不想在 niri 启动时看到快捷键帮助浮层设置此标志hotkey-overlay { skip-at-startup }hide-not-bound隐藏未绑定的动作自 25.08 版本可用。默认情况下即使某些重要动作没有绑定任何按键niri 也会显示它们以避免困惑。设置hide-not-bound可隐藏所有未绑定按键的动作hotkey-overlay { hide-not-bound }你还可以通过hotkey-overlay-title属性 自定义浮层展示哪些绑定及其标题。config-notification配置通知设置自 25.08 版本可用。配置创建/解析失败通知的相关设置。设置disable-failed可禁用Failed to parse the config file配置文件解析失败通知例如当你已有自制的通知方案时config-notification { disable-failed }blur全局背景模糊配置自 26.04 版本可用。影响所有背景模糊的全局配置背景效果总览请参见窗口效果Window Effects。以下为默认值// 这些是默认值 blur { // off passes 3 offset 3 noise 0.02 saturation 1.5 }对应结构体Blur与默认实现位于 niri-config/src/appearance.rs。模糊配置会被注入到窗口与图层表面的渲染管线中见 src/window/mapped.rs 与 src/layer/mapped.rs。off完全禁用模糊默认情况下模糊按需可用窗口或图层表面可通过ext-background-effect协议请求你也可以通过窗口规则或图层规则中的background-effect手动启用blur true。设置off标志将禁用所有模糊——无论是窗口请求的还是窗口规则里配置的blur { off }passes与offset双重 Kawase 模糊的趟数与偏移passes控制双 Kawasedual kawase模糊的下采样/上采样趟数。趟数越多模糊范围越大、越平滑但 GPU 开销也越高。offset是每趟的像素偏移倍率。offset 1即原始 dual kawase 模糊更大的值产生更平滑的模糊且不增加 GPU 开销。但offset设得过大会产生视觉伪影此时需要增加passes才能在不出现伪影的情况下使用更大的offset。调参建议先增大offset因为它不增加 GPU 负载直到开始出现伪影如果仍需要更平滑的模糊再把passes加 1如此反复直到获得理想的视觉效果blur { passes 3 offset 3.0 }在渲染端趟数会被限制在 1–31 之间offset通过 uniform 传给着色器见 src/render_helpers/blur.rs 与 src/render_helpers/blur.rs。解析时offset的合法区间为 0–100FloatOrInt0, 100见 niri-config/src/appearance.rs。noise噪声量叠加在模糊之上的噪声量有助于减少颜色带状color banding伪影blur { noise 0.02 }解析区间为FloatOrInt0, 1000见 niri-config/src/appearance.rs。saturation饱和度作用于模糊背景的颜色饱和度。大于1提高饱和度小于1降低饱和度blur { saturation 1.5 }解析区间同为FloatOrInt0, 1000见 niri-config/src/appearance.rs。小结以上顶层选项共同构成了 niri 配置中不单独成章的部分它们全部位于配置文件的顶层而非binds、layout等区块内。配置默认值来自内置的default-config.kdl由Config::load_default()加载见 niri-config/src/lib.rs首次启动时 niri 也会自动创建带默认注释的用户配置文件见 niri-config/src/lib.rs。在实际使用中有几个关键区分值得记住对运行中的应用即时生效与否prefer-no-csd与clipboard.disable-primary都只对新启动/重新协商的应用完整生效修改后建议重启相关应用生效范围environment只影响 niri 派生的进程不会写入 systemd 全局环境作用域差异overview.backdrop-color可在输出配置中按输出覆盖blur则是全局开关可被窗口/图层规则进一步细化。若希望以最小配置快速验证本文中的选项可在~/.config/niri/config.kdl中组合书写上述代码块并重启 niri或以niri --config /path/to/config.kdl指定配置文件见 src/cli.rs。配置文件支持include拆分递归上限 10 层见 niri-config/src/lib.rs方便把杂项单独维护为一个文件再引入主配置。【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考