niri 发行版集成指南配置分发、Xwayland、自启动与桌面组件接入【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri本篇指南面向发行版打包维护者、系统集成工程师以及希望深度定制 niri 桌面环境的进阶用户围绕 niri一个可滚动平铺的 Wayland 合成器在发行版与桌面环境中的集成展开从配置文件加载优先级与发行版默认配置分发到 Xwayland 兼容层、键盘布局读取、systemd 自启动、屏幕阅读器支持以及桌面组件与外壳的预配置再到 niri 的安全模型。读完本文你将掌握如何在发行版中正确打包和预置 niri、通过/etc或环境变量控制配置来源并为用户提供开箱即用的完整桌面体验。关于创建 niri 软件包的具体流程请参见 Packaging-niri.md 页面。配置文件加载与发行版默认配置分发niri 使用 KDL 格式的配置文件。加载配置时niri 会按照以下优先级寻找配置文件$XDG_CONFIG_HOME/niri/config.kdl未设置XDG_CONFIG_HOME时为~/.config/niri/config.kdl回退到/etc/niri/config.kdl如果上述文件都不存在niri 会创建$XDG_CONFIG_HOME/niri/config.kdl并将其内容写为 default-config.kdl 的内容——这份默认配置在构建时被嵌入到 niri 二进制中。这条规则对发行版维护者意义重大自定义发行版默认配置只要创建/etc/niri/config.kdl即可覆盖默认设置向用户分发经过定制的默认配置注意配置创建行为的变化当/etc/niri/config.kdl存在时niri不会自动在~/.config/niri/创建用户配置。因此发行版需要向用户说明如何自行创建个人配置例如复制/etc/niri/config.kdl到~/.config/niri/config.kdl后自行编辑跟随上游更新niri 会在新版本中更新默认配置因此如果发行版维护了自定义的/etc/niri/config.kdl在新版本发布时应检查并应用相关的默认配置变更避免新功能因旧配置而缺失或被禁用。从源码实现看配置路径解析逻辑位于 src/main.rs 的config_path()函数命令行参数--config优先级最高其次为环境变量最后才是上述默认位置同时system_config_path()直接返回/etc/niri/config.kdl与文档描述一致。niri 也提供niri validate子命令同样支持--config参数用于校验配置文件。用 NIRI_CONFIG 覆盖配置路径默认配置位置可以通过NIRI_CONFIG环境变量覆盖。这一机制对测试、临时配置和容器/CI 场景尤其有用NIRI_CONFIG/path/to/config.kdl niri注意在src/main.rs中加载配置后会立即执行env::remove_var(NIRI_CONFIG)避免该环境变量被传递给后续启动的子进程如spawn-at-startup启动的应用造成混淆。运行时热切换配置自版本 26.04 起。除了启动时指定配置niri 还支持在运行时通过 IPC 修改配置路径并重新加载niri msg action load-config-file --path path-to-config.kdl执行该命令后niri 会加载指定的新配置文件并应用。从 src/ipc/server.rs 的实现看该动作要求路径必须指向一个实际存在的文件path does not point to a file校验且相对路径会基于 niri 合成器的当前工作目录解析——因此建议始终使用绝对路径。将配置拆分为多个文件include自版本 25.11 起。你可以在配置文件的顶层使用include指令拆分配置将主题、键位、输出设置等拆分到独立文件中管理。详细语法与合并语义见 Configuration:-Include.md这里摘录要点包含文件与主配置文件结构相同其中的设置会与主配置合并被包含的文件还可以继续包含其他文件所有被包含的文件都会被监听任一文件变化都会触发配置热重载包含方式支持相对路径相对于当前文件如other.kdl或./other.kdl、绝对路径/path/to/file.kdl自 26.04 起还支持~/file.kdl形式的主目录展开include只能出现在配置顶层不能嵌在其他区块内部include 是位置相关的它会覆盖其之前设置的选项而之后的设置会再覆盖它包含文件中的window-rule会插入到include行所在位置自 26.04 起支持include optionaltrue optional-config.kdl文件缺失时仅发出警告而不会报错且该文件仍会被监听之后创建它时会自动重载生效大部分配置区块如layout的子节在 include 之间是合并的可以只修改其中几个属性但window-rule、output、workspace等多段式区块按原样插入不合并binds会覆盖先前冲突的按键struts、preset-column-widths、animations的子节、input中的指针设备节等表示组合结构的区块不合并。一个发行版集成上的特殊注意点在主配置中写layout { border {} }会启用边框等价于layout { border { on; } }但在被包含的配置文件中写同样的内容却不会生效因为没有任何属性被修改。因此若将 layout 配置从主配置迁移到独立文件记得在 border 节中显式加上on// separate.kdl layout { border { // 加上这一行 on width 4 active-color #ffc87f inactive-color #505050 } }Xwayland 兼容层xwayland-satellite 集成Xwayland 是运行 X11 应用与游戏所必需的同时 Orca 屏幕阅读器也依赖它。自版本 25.08 起niri 开箱即用地集成了 xwayland-satellite。该集成要求$PATH中存在xwayland-satellite 0.7。发行版打包时请考虑让 niri 依赖或至少推荐xwayland-satellite 软件包。如果你的用户或发行版默认配置之前手动启动了xwayland-satellite并手动设置了$DISPLAY应移除这些自定义配置以便自动集成正常工作。从源码实现看集成逻辑位于 src/utils/xwayland/satellite.rs在 src/main.rs 启动流程中被调用xwayland::satellite::setup(mut state)。实现会尝试打开 X11 套接字并探测 xwayland-satellite 是否支持按需激活on-demand activation若二进制缺失、启动失败或不支持按需激活集成会被自动禁用并记录警告日志而不是让 niri 崩溃。实现中还包含对事件源忙循环busyloop的规避处理当 xwayland-satellite 启动失败时会清空套接字上挂起的连接。可以通过xwayland-satellite顶层选项 修改 niri 查找 xwayland-satellite 可执行文件的路径。X11 应用的更多注意事项参见 Xwayland.md。键盘布局从 systemd-localed 读取自版本 25.08 起。默认情况下除非在配置中手动指定了 layoutniri 会通过 D-Bus 从 systemd-localedorg.freedesktop.locale1读取键盘布局设置。这对发行版安装器有直接指导意义请确保系统安装程序通过 systemd-localed 设置键盘布局这样 niri 启动后即可自动拾取正确的布局无需用户额外配置。从代码结构看该 D-Bus 集成位于 src/dbus/freedesktop_locale1.rs属于src/dbus模块下的一组 freedesktop D-Bus 服务集成之一。相关的手动配置方法键盘布局、变体等参见 Configuration:-Input.md。自启动systemd 集成与桌面组件niri 与标准的 systemd 自启动机制完全兼容。默认的 niri.service 单元会拉起graphical-session.target以及xdg-desktop-autostart.target这意味着系统级的桌面自启动约定如~/.config/autostart/中的.desktop文件可以无缝工作。完整的服务单元内容如下[Unit] DescriptionA scrollable-tiling Wayland compositor BindsTographical-session.target Beforegraphical-session.target Wantsgraphical-session-pre.target Aftergraphical-session-pre.target Wantsxdg-desktop-autostart.target Beforexdg-desktop-autostart.target [Service] Slicesession.slice Typenotify ExecStartniri --session该单元使用Typenotifyniri 就绪后通过 sd_notify 通知 systemd并绑定到graphical-session.target的生命周期。让程序随 niri 启动的三种方式XDG autostart将程序的.desktop文件链接到~/.config/autostart/由xdg-desktop-autostart.target统一拉起systemd 服务编写带WantedBygraphical-session.target的.service文件或通过systemctl --user add-wants niri.service name.service将现有服务挂到 niri 会话下niri 配置在配置中加入spawn-at-startup以及需要执行 shell 命令时的spawn-sh-at-startup行例如默认配置中的spawn-at-startup waybar。更多完整示例参见 Example-systemd-Setup.md其中演示了如何将 mako、waybar、swaybg、swayidle 等作为 systemd 服务随 niri 会话启动与重启以及通过systemd-run --user --scope让程序如 tmux在登出后继续存活。屏幕阅读器与无障碍支持自版本 25.08 起niri 支持 Orca 屏幕阅读器。Orca 依赖 Xwayland 运行这也是上文强调 Xwayland 必要性的原因之一。面向无障碍需求较高的发行版具体的无障碍配置细节与建议见 Accessibility.md 页面niri 的无障碍AccessKit适配代码位于 src/a11y.rs。桌面组件与外壳让默认会话更完整发行版打包 niri 时用户大概率还需要至少一个通知守护进程、xdg-desktop-portal 实现以及认证代理。详细清单见 Important-Software.md 页面。在此基础上可以预配置一些桌面外壳组件避免默认会话过于简陋状态栏niri 默认配置会启动 Waybar这是一个不错的起点发行版可以考虑调整其默认配置以精简内容并加入niri/workspaces模块以展示 niri 的工作区壁纸工具建议提供桌面背景工具例如 swaybg 或 awww原 swww屏幕锁定默认的swaylock之外可以预置更美观的锁屏如 hyprlock。与完整桌面环境/外壳协同如果希望提供更一体化、更“开箱即用”的体验可以选择让 niri 与现有的桌面环境或外壳协同工作LXQt 官方支持 niri设置方式见其 Wayland 会话文档XFCE 的许多组件可在 Wayland 下运行包括 niri各组件支持状态见其 Wayland 路线图基于 Quickshell 的完整桌面外壳有支持 niri 的现成项目例如 DankMaterialShell 与 Noctalia可以使用 cosmic-ext-extra-sessions 在 niri 上运行 COSMIC 会话。安全模型niri 采用 Wayland 合成器的典型安全模型。关于窗口隔离、输入事件、截屏权限、IPC 与 D-Bus 接口等安全机制的详细说明参见 Security-Model.md 页面。集成检查清单综合上文发行版或系统集成者在交付 niri 时应逐项确认配置分发决定使用内置默认配置还是创建/etc/niri/config.kdl定制默认值若使用后者向用户文档中说明如何初始化个人配置并在 niri 新版本发布时同步检查默认配置变更Xwayland依赖或推荐xwayland-satellite 0.7并确保其位于$PATH移除旧的手动启动/$DISPLAY配置键盘布局确保安装器通过 systemd-localedorg.freedesktop.locale1写入键盘布局自启动确认graphical-session.target与xdg-desktop-autostart.target被拉起将系统组件以.desktop、WantedBygraphical-session.target的服务或spawn-at-startup接入会话桌面组件预置通知守护进程、portal、认证代理视需要补充 Waybar含niri/workspaces模块、壁纸工具与更完善的锁屏无障碍确认 Xwayland 可用以支持 Orca 屏幕阅读器并参考无障碍文档为无障碍发行版做针对性配置安全向用户/安全团队提供 niri 安全模型的说明文档链接。【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考