企业官网建设流程全解析

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 optional=true "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 起。

默认情况下（除非在配置中手动指定了 layout），niri 会通过 D-Bus 从 systemd-localed（org.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] Description=A scrollable-tiling Wayland compositor BindsTo=graphical-session.target Before=graphical-session.target Wants=graphical-session-pre.target After=graphical-session-pre.target Wants=xdg-desktop-autostart.target Before=xdg-desktop-autostart.target [Service] Slice=session.slice Type=notify ExecStart=niri --session

该单元使用Type=notify（niri 就绪后通过 sd_notify 通知 systemd），并绑定到graphical-session.target的生命周期。

让程序随 niri 启动的三种方式

1. XDG autostart：将程序的.desktop文件链接到~/.config/autostart/，由xdg-desktop-autostart.target统一拉起；
2. systemd 服务：编写带WantedBy=graphical-session.target的.service文件，或通过systemctl --user add-wants niri.service <name>.service将现有服务挂到 niri 会话下；
3. 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 时应逐项确认：

1. 配置分发：决定使用内置默认配置，还是创建/etc/niri/config.kdl定制默认值；若使用后者，向用户文档中说明如何初始化个人配置，并在 niri 新版本发布时同步检查默认配置变更；
2. Xwayland：依赖或推荐xwayland-satellite >= 0.7并确保其位于$PATH，移除旧的手动启动/$DISPLAY配置；
3. 键盘布局：确保安装器通过 systemd-localed（org.freedesktop.locale1）写入键盘布局；
4. 自启动：确认graphical-session.target与xdg-desktop-autostart.target被拉起，将系统组件以.desktop、WantedBy=graphical-session.target的服务或spawn-at-startup接入会话；
5. 桌面组件：预置通知守护进程、portal、认证代理，视需要补充 Waybar（含niri/workspaces模块）、壁纸工具与更完善的锁屏；
6. 无障碍：确认 Xwayland 可用以支持 Orca 屏幕阅读器，并参考无障碍文档为无障碍发行版做针对性配置；
7. 安全：向用户/安全团队提供 niri 安全模型的说明文档链接。

【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri