企业官网建设流程全解析

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 x=0 y=10 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: Vec<String>（见 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被解析为Vec<EnvironmentVariable>（见 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.rs），xcursor-size的类型为u8（0–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: Option<u32>（见 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被限定在FloatOrInt<0, 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控制双 Kawase（dual 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–100（FloatOrInt<0, 100>，见 niri-config/src/appearance.rs）。

noise：噪声量

叠加在模糊之上的噪声量，有助于减少颜色带状（color banding）伪影：

blur { noise 0.02 }

解析区间为FloatOrInt<0, 1000>（见 niri-config/src/appearance.rs）。

saturation：饱和度

作用于模糊背景的颜色饱和度。大于1提高饱和度，小于1降低饱和度：

blur { saturation 1.5 }

解析区间同为FloatOrInt<0, 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