拓冰网站定制 
niri 配置入门KDL 语法、配置加载与实时重载完全指南【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri导读niri 是一个可横向滚动的平铺式 Wayland 合成器其全部行为——从输入设备、输出布局、窗口规则到按键绑定——都由一个基于 KDL 为骨架系统讲解 niri 配置文件的存放与加载机制、--config/$NIRI_CONFIG的优先级规则、niri validate校验命令以及 KDL 语法中的注释、Flag 开关、重复节Section约束与默认值行为并结合仓库源码niri-config/src/lib.rs、src/main.rs、src/utils/watcher.rs剖析其底层实现。读完本文你将能独立编写、校验、调试并热重载自己的 niri 配置。配置文件的查找与加载niri 启动时会按固定的优先级查找配置文件逻辑实现在 src/main.rs 的config_path()函数中命令行参数优先niri --config PATH或niri -c PATH显式指定路径环境变量次之$NIRI_CONFIG指向配置文件路径--config总是优先于环境变量见 src/main.rsCLI 文档注释见 src/cli.rs默认位置$XDG_CONFIG_HOME/niri/config.kdl若$XDG_CONFIG_HOME未设置则回退到~/.config/niri/config.kdl系统级回退/etc/niri/config.kdl。上述默认路径在 src/main.rs 中通过ProjectDirs::from(, , niri)计算用户目录系统路径则硬编码为/etc/niri/config.kdl。默认配置的自动生成如果用户配置和系统配置都不存在niri 会在首次启动时自动创建$XDG_CONFIG_HOME/niri/config.kdl并写入构建时嵌入二进制内的默认配置内容。源码实现位于 src/main.rs 的load_or_create()调用以及 niri-config/src/lib.rs 的create()方法使用create_new(true)原子创建文件若文件已存在则直接返回避免覆盖用户已有的修改默认配置内容来自resources/default-config.kdl通过include_bytes!编译期嵌入。因此官方建议以默认配置文件作为自定义配置的起点。你可以随时参考仓库中的 resources/default-config.kdl 这份完整注释版默认配置其中包含了各节的详细注释和大量示例。特殊路径行为--config或$NIRI_CONFIG指向的文件不存在时配置不会被加载即使用Explicit模式时不会自动创建见 niri-config/src/lib.rs 中ConfigPath::Explicit的语义$NIRI_CONFIG被设置为空字符串时会被忽略回落到默认配置位置见 src/main.rs 的env_config_path()通过.filter(|x| !x.is_empty())实现配置文件加载失败时niri 会打印错误日志并回退到内置默认配置继续运行同时弹出一个配置错误通知见 src/main.rs 与 src/niri.rs。配置校验niri validate你可以运行niri validate来解析配置文件并查看任何错误。该子命令在 src/cli.rs 中定义支持与主命令相同的--config/-c参数其执行逻辑在 src/main.rsSub::Validate { config } { tracy_client::Client::start(); config_path(config).load().config?; info!(config is valid); return Ok(()); }即按照与启动时完全相同的查找规则定位配置文件调用ConfigPath::load()解析解析成功则打印config is valid并返回 0失败则输出包含具体行列位置的诊断信息并返回非零退出码。在修改配置后、重启或依赖热重载之前先用niri validate做一次语法检查是最稳妥的实践。实时热重载niri 的配置是**实时重载live-reloaded**的编辑并保存配置文件后改动会立即生效无需重启合成器。覆盖范围包括按键绑定、输出设置如分辨率 mode、窗口规则等所有配置项。其实现由一个独立的后台线程完成位于 src/utils/watcher.rs主配置与所有include进来的文件都会被监视以 500ms 为间隔轮询POLLING_INTERVAL Duration::from_millis(500)见 src/utils/watcher.rs文件属性Props其包含修改时间 mtime与规范化路径 canonical两个字段见 src/utils/watcher.rs——同时记录 canonical 路径是为了兼容 Nix/NixOS 这类 mtime 恒为 epoch、靠符号链接切换配置生成版本的场景测试swap_just_link、swap_many_links_regular_like_nix专门覆盖了该情形检测到变化后在 watcher 线程上重新解析配置解析耗时较长避免阻塞事件循环再通过 channel 把结果送回主事件循环由State::reload_config()src/niri.rs应用隐藏/显示配置错误通知、清理被移除的命名工作区、更新布局与 layer-surface 配置、重新创建新增命名工作区并刷新动画参数等。配套的单元测试位于 src/utils/watcher.rs覆盖了修改文件、touch 无内容变化、删除后重建、符号链接切换、include 文件变化/缺失/嵌套、以及损坏的 include 仍会被监视、修复后自动重载等边界场景。KDL 语法基础配置文件使用 KDL 书写。KDL 是一种节点化的配置文件语言niri 通过knuffel解析库将 KDL 文档解码为Config结构体见 niri-config/src/lib.rs。下面介绍撰写 niri 配置必须掌握的语法要点。注释以//开头的行是注释会被忽略。此外在节section前面加上/-可以注释掉整个节/-output eDP-1 { // Everything inside here is ignored. // The display wont be turned off // as the whole section is commented out. off }/-注释掉整个节点对想保留示例、暂时禁用的场景非常有用——resources/default-config.kdl中多处使用该语法例如 resources/default-config.kdl 的/-output eDP-1 {...}与/-window-rule {...}示例。Flag 开关niri 中的布尔开关型选项通常以Flag形式表示写出该 flag 即启用省略或注释掉即禁用。例如焦点跟随鼠标// Focus follows mouse is enabled. input { focus-follows-mouse // Other settings... }// Focus follows mouse is disabled. input { // focus-follows-mouse // Other settings... }从源码看Flag 是一个可携带可选显式值的三态类型niri-config/src/utils.rs缺省不写未设置保持默认只写field设为true显式写field true或field false明确设为true或false。因此prefer-no-csd、warp-mouse-to-focus等 flag 也可以写成带显式值的形式例如prefer-no-csd false这在与include配合时尤为重要下文详述。节Sections与重复约束大多数节不能重复出现。例如input节在同一个文件中只能写一次// This is valid: every section appears once. input { keyboard { // ... } touchpad { // ... } }以下写法不合法input节出现了两次input { keyboard { // ... } } input { touchpad { // ... } }例外是按名称配置不同设备的节如output、window-rule、layer-rule、workspace、spawn-at-startup等多部分multipart节output eDP-1 { // ... } // This is valid: this section configures a different output. output HDMI-A-1 { // ... } // This is NOT valid: eDP-1 already appeared above. // It will either throw a config parsing error, or otherwise not work. output eDP-1 { // ... }源码中的重复检测实现在 niri-config/src/lib.rs解析器维护一个seen集合对不属于上述白名单的节点若名字重复则抛出duplicate node{name}, single node expected错误。白名单output、spawn-at-startup、spawn-sh-at-startup、window-rule、layer-rule、workspace、include都是追加新条目性质的节因此允许重复。默认值省略配置文件中的大部分节会保留该节的默认值。唯一的显著例外是binds {}它不会被填入默认值所以千万不要删掉这个节——否则你的按键绑定会全部失效。这一点在 niri-config/src/lib.rs 的模块文档中也有明确说明Default值在几乎所有情况下与default-config.kdl一致唯一显著例外是binds {}和部分 window-rule。相应的测试default_repeat_paramsniri-config/src/lib.rs验证了空配置下键盘重复延迟/速率仍取默认值 600ms / 25Hz。各配置节的索引Configuration: Introduction文档将各节的详细说明分散在独立页面中。下面把链接转换为仓库根目录相对路径方便按需查阅节详细文档input {}Configuration: Inputoutput eDP-1 {}Configuration: Outputsbinds {}Configuration: Key Bindingsswitch-events {}Configuration: Switch Eventslayout {}Configuration: Layout顶层选项Configuration: Miscellaneouswindow-rule {}Configuration: Window Ruleslayer-rule {}Configuration: Layer Rulesanimations {}Configuration: Animationsgestures {}Configuration: Gesturesrecent-windows {}Configuration: Recent Windowsdebug {}Configuration: Debug Optionsinclude other.kdlConfiguration: Include配置文件拆分include除了单一配置文件niri 还支持通过include指令把配置拆分为多个文件详见 Configuration: Include这在整理大型配置时非常实用。核心要点include 只能出现在顶层不能在某个节内部使用路径支持相对当前文件other.kdl、绝对路径/path/to/file.kdl以及~/file.kdl家目录展开include 是**位置相关positional**的被包含文件中的设置会覆盖它之前的设置其内的window-rule等会插入到 include 语句所在的位置被包含的文件同样会被监视任意一个变化都会触发整份配置的热重载支持include optionaltrue file.kdl文件缺失时仅告警而不报错且缺失文件仍会被监视创建后自动重载生效。include 的底层实现在 niri-config/src/lib.rs包括~展开、递归深度限制RECURSION_LIMIT 10见 niri-config/src/lib.rs、递归 include 检测提供更友好的错误信息、以及被包含文件的解析错误收集等。破坏性变更策略Breaking Change Policy作为规则niri 的版本更新不应破坏现有配置文件——例如 v0.1.0 的默认配置在撰写本文时仍可在 v25.02 上正常解析。但在两种情况下存在例外**解析缺陷parsing bugs**的修复可以破坏兼容。一个实例niri 过去曾静默接受同一按键的多个绑定实际上只有第一个生效某个补丁版本将其改为解析失败以暴露这一未预期的错误用法该策略只适用于正式发布版本。版本之间的提交commit会偶尔破坏配置——新特性打磨过程中这是不可避免的但作者会尽量限制这类变更因为有不少用户在使用 git 构建版。因此升级 niri 时若配置解析失败先核对官方发布说明中的配置变更若在 git 构建版之间遇到问题这属于正常的新特性演进过程。一个可运行的完整示例下面把本文要点串成一个最小但完整的配置骨架完整默认配置见 resources/default-config.kdl你可以把它作为起点修改// 输入设置开启焦点跟随鼠标 input { focus-follows-mouse } // 输出设置给笔记本内屏配置缩放 /-output eDP-1 { scale 2 mode 1920x1080120.030 } // 布局设置间距与焦点环 layout { gaps 16 focus-ring { width 4 active-color #7fc8ff inactive-color #505050 } } // 启动时运行程序 spawn-at-startup waybar // 按键绑定务必保留此节它不会被填充默认值 binds { ModT { spawn alacritty; } ModQ { close-window; } ModShiftE { quit; } }修改后先执行niri validate确认无误再保存到~/.config/niri/config.kdl运行中的 niri 会在 500ms 内自动热重载。若希望加载另一份配置用niri -c /path/to/config.kdl启动即可。【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 niri 配置入门：KDL 语法、配置加载与实时重载完全指南
niri 配置入门KDL 语法、配置加载与实时重载完全指南【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri导读niri 是一个可横向滚动的平铺式 Wayland 合成器其全部行为——从输入设备、输出布局、窗口规则到按键绑定——都由一个基于 KDL 为骨架系统讲解 niri 配置文件的存放与加载机制、--config/$NIRI_CONFIG的优先级规则、niri validate校验命令以及 KDL 语法中的注释、Flag 开关、重复节Section约束与默认值行为并结合仓库源码niri-config/src/lib.rs、src/main.rs、src/utils/watcher.rs剖析其底层实现。读完本文你将能独立编写、校验、调试并热重载自己的 niri 配置。配置文件的查找与加载niri 启动时会按固定的优先级查找配置文件逻辑实现在 src/main.rs 的config_path()函数中命令行参数优先niri --config PATH或niri -c PATH显式指定路径环境变量次之$NIRI_CONFIG指向配置文件路径--config总是优先于环境变量见 src/main.rsCLI 文档注释见 src/cli.rs默认位置$XDG_CONFIG_HOME/niri/config.kdl若$XDG_CONFIG_HOME未设置则回退到~/.config/niri/config.kdl系统级回退/etc/niri/config.kdl。上述默认路径在 src/main.rs 中通过ProjectDirs::from(, , niri)计算用户目录系统路径则硬编码为/etc/niri/config.kdl。默认配置的自动生成如果用户配置和系统配置都不存在niri 会在首次启动时自动创建$XDG_CONFIG_HOME/niri/config.kdl并写入构建时嵌入二进制内的默认配置内容。源码实现位于 src/main.rs 的load_or_create()调用以及 niri-config/src/lib.rs 的create()方法使用create_new(true)原子创建文件若文件已存在则直接返回避免覆盖用户已有的修改默认配置内容来自resources/default-config.kdl通过include_bytes!编译期嵌入。因此官方建议以默认配置文件作为自定义配置的起点。你可以随时参考仓库中的 resources/default-config.kdl 这份完整注释版默认配置其中包含了各节的详细注释和大量示例。特殊路径行为--config或$NIRI_CONFIG指向的文件不存在时配置不会被加载即使用Explicit模式时不会自动创建见 niri-config/src/lib.rs 中ConfigPath::Explicit的语义$NIRI_CONFIG被设置为空字符串时会被忽略回落到默认配置位置见 src/main.rs 的env_config_path()通过.filter(|x| !x.is_empty())实现配置文件加载失败时niri 会打印错误日志并回退到内置默认配置继续运行同时弹出一个配置错误通知见 src/main.rs 与 src/niri.rs。配置校验niri validate你可以运行niri validate来解析配置文件并查看任何错误。该子命令在 src/cli.rs 中定义支持与主命令相同的--config/-c参数其执行逻辑在 src/main.rsSub::Validate { config } { tracy_client::Client::start(); config_path(config).load().config?; info!(config is valid); return Ok(()); }即按照与启动时完全相同的查找规则定位配置文件调用ConfigPath::load()解析解析成功则打印config is valid并返回 0失败则输出包含具体行列位置的诊断信息并返回非零退出码。在修改配置后、重启或依赖热重载之前先用niri validate做一次语法检查是最稳妥的实践。实时热重载niri 的配置是**实时重载live-reloaded**的编辑并保存配置文件后改动会立即生效无需重启合成器。覆盖范围包括按键绑定、输出设置如分辨率 mode、窗口规则等所有配置项。其实现由一个独立的后台线程完成位于 src/utils/watcher.rs主配置与所有include进来的文件都会被监视以 500ms 为间隔轮询POLLING_INTERVAL Duration::from_millis(500)见 src/utils/watcher.rs文件属性Props其包含修改时间 mtime与规范化路径 canonical两个字段见 src/utils/watcher.rs——同时记录 canonical 路径是为了兼容 Nix/NixOS 这类 mtime 恒为 epoch、靠符号链接切换配置生成版本的场景测试swap_just_link、swap_many_links_regular_like_nix专门覆盖了该情形检测到变化后在 watcher 线程上重新解析配置解析耗时较长避免阻塞事件循环再通过 channel 把结果送回主事件循环由State::reload_config()src/niri.rs应用隐藏/显示配置错误通知、清理被移除的命名工作区、更新布局与 layer-surface 配置、重新创建新增命名工作区并刷新动画参数等。配套的单元测试位于 src/utils/watcher.rs覆盖了修改文件、touch 无内容变化、删除后重建、符号链接切换、include 文件变化/缺失/嵌套、以及损坏的 include 仍会被监视、修复后自动重载等边界场景。KDL 语法基础配置文件使用 KDL 书写。KDL 是一种节点化的配置文件语言niri 通过knuffel解析库将 KDL 文档解码为Config结构体见 niri-config/src/lib.rs。下面介绍撰写 niri 配置必须掌握的语法要点。注释以//开头的行是注释会被忽略。此外在节section前面加上/-可以注释掉整个节/-output eDP-1 { // Everything inside here is ignored. // The display wont be turned off // as the whole section is commented out. off }/-注释掉整个节点对想保留示例、暂时禁用的场景非常有用——resources/default-config.kdl中多处使用该语法例如 resources/default-config.kdl 的/-output eDP-1 {...}与/-window-rule {...}示例。Flag 开关niri 中的布尔开关型选项通常以Flag形式表示写出该 flag 即启用省略或注释掉即禁用。例如焦点跟随鼠标// Focus follows mouse is enabled. input { focus-follows-mouse // Other settings... }// Focus follows mouse is disabled. input { // focus-follows-mouse // Other settings... }从源码看Flag 是一个可携带可选显式值的三态类型niri-config/src/utils.rs缺省不写未设置保持默认只写field设为true显式写field true或field false明确设为true或false。因此prefer-no-csd、warp-mouse-to-focus等 flag 也可以写成带显式值的形式例如prefer-no-csd false这在与include配合时尤为重要下文详述。节Sections与重复约束大多数节不能重复出现。例如input节在同一个文件中只能写一次// This is valid: every section appears once. input { keyboard { // ... } touchpad { // ... } }以下写法不合法input节出现了两次input { keyboard { // ... } } input { touchpad { // ... } }例外是按名称配置不同设备的节如output、window-rule、layer-rule、workspace、spawn-at-startup等多部分multipart节output eDP-1 { // ... } // This is valid: this section configures a different output. output HDMI-A-1 { // ... } // This is NOT valid: eDP-1 already appeared above. // It will either throw a config parsing error, or otherwise not work. output eDP-1 { // ... }源码中的重复检测实现在 niri-config/src/lib.rs解析器维护一个seen集合对不属于上述白名单的节点若名字重复则抛出duplicate node{name}, single node expected错误。白名单output、spawn-at-startup、spawn-sh-at-startup、window-rule、layer-rule、workspace、include都是追加新条目性质的节因此允许重复。默认值省略配置文件中的大部分节会保留该节的默认值。唯一的显著例外是binds {}它不会被填入默认值所以千万不要删掉这个节——否则你的按键绑定会全部失效。这一点在 niri-config/src/lib.rs 的模块文档中也有明确说明Default值在几乎所有情况下与default-config.kdl一致唯一显著例外是binds {}和部分 window-rule。相应的测试default_repeat_paramsniri-config/src/lib.rs验证了空配置下键盘重复延迟/速率仍取默认值 600ms / 25Hz。各配置节的索引Configuration: Introduction文档将各节的详细说明分散在独立页面中。下面把链接转换为仓库根目录相对路径方便按需查阅节详细文档input {}Configuration: Inputoutput eDP-1 {}Configuration: Outputsbinds {}Configuration: Key Bindingsswitch-events {}Configuration: Switch Eventslayout {}Configuration: Layout顶层选项Configuration: Miscellaneouswindow-rule {}Configuration: Window Ruleslayer-rule {}Configuration: Layer Rulesanimations {}Configuration: Animationsgestures {}Configuration: Gesturesrecent-windows {}Configuration: Recent Windowsdebug {}Configuration: Debug Optionsinclude other.kdlConfiguration: Include配置文件拆分include除了单一配置文件niri 还支持通过include指令把配置拆分为多个文件详见 Configuration: Include这在整理大型配置时非常实用。核心要点include 只能出现在顶层不能在某个节内部使用路径支持相对当前文件other.kdl、绝对路径/path/to/file.kdl以及~/file.kdl家目录展开include 是**位置相关positional**的被包含文件中的设置会覆盖它之前的设置其内的window-rule等会插入到 include 语句所在的位置被包含的文件同样会被监视任意一个变化都会触发整份配置的热重载支持include optionaltrue file.kdl文件缺失时仅告警而不报错且缺失文件仍会被监视创建后自动重载生效。include 的底层实现在 niri-config/src/lib.rs包括~展开、递归深度限制RECURSION_LIMIT 10见 niri-config/src/lib.rs、递归 include 检测提供更友好的错误信息、以及被包含文件的解析错误收集等。破坏性变更策略Breaking Change Policy作为规则niri 的版本更新不应破坏现有配置文件——例如 v0.1.0 的默认配置在撰写本文时仍可在 v25.02 上正常解析。但在两种情况下存在例外**解析缺陷parsing bugs**的修复可以破坏兼容。一个实例niri 过去曾静默接受同一按键的多个绑定实际上只有第一个生效某个补丁版本将其改为解析失败以暴露这一未预期的错误用法该策略只适用于正式发布版本。版本之间的提交commit会偶尔破坏配置——新特性打磨过程中这是不可避免的但作者会尽量限制这类变更因为有不少用户在使用 git 构建版。因此升级 niri 时若配置解析失败先核对官方发布说明中的配置变更若在 git 构建版之间遇到问题这属于正常的新特性演进过程。一个可运行的完整示例下面把本文要点串成一个最小但完整的配置骨架完整默认配置见 resources/default-config.kdl你可以把它作为起点修改// 输入设置开启焦点跟随鼠标 input { focus-follows-mouse } // 输出设置给笔记本内屏配置缩放 /-output eDP-1 { scale 2 mode 1920x1080120.030 } // 布局设置间距与焦点环 layout { gaps 16 focus-ring { width 4 active-color #7fc8ff inactive-color #505050 } } // 启动时运行程序 spawn-at-startup waybar // 按键绑定务必保留此节它不会被填充默认值 binds { ModT { spawn alacritty; } ModQ { close-window; } ModShiftE { quit; } }修改后先执行niri validate确认无误再保存到~/.config/niri/config.kdl运行中的 niri 会在 500ms 内自动热重载。若希望加载另一份配置用niri -c /path/to/config.kdl启动即可。【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考