niri 中的 X11 兼容方案xwayland-satellite 集成与多种运行 X11 应用的实操指南【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niriX11 应用Steam、Discord、游戏、旧版工具链至今仍是 Linux 桌面绕不开的兼容性话题而 niri 作为滚动平铺 Wayland 合成器选择了与其他合成器不同的路线不直接内嵌 Xwayland而是开箱即用地集成 xwayland-satellite把 X11 的诅咒隔离在合成器之外。本文以 Xwayland.md 为骨架结合 xwayland-satellite 集成源码 与 配置实现完整讲解 niri 自动集成 xwayland-satellite 的机制、xwayland-satellite配置块的用法以及多种运行 X11 应用的嵌套方案labwc、rootful Xwayland、xwayland-run、Cage、gamescope、Proton-GE 原生 Wayland读完即可按需选用。一、开箱即用的 xwayland-satellite 集成自 25.08 起niri 与 xwayland-satellite 开箱即用集成。只要安装xwayland-satellite 0.7并确保其位于$PATH中无需任何额外配置niri 就会在磁盘上创建 X11 套接字导出$DISPLAY环境变量当有 X11 客户端连接时按需on-demand启动 xwayland-satellite若 xwayland-satellite 退出niri 会自动重新启动它。如果你之前在自定义配置里手动启动过xwayland-satellite并手工设置过$DISPLAY请删除这些自定义否则会与自动集成冲突。验证集成是否生效启动 niri 后检查 niri 的输出中是否出现listening on X11 socket: :0之类的日志$ journalctl --user-unitniri -b systemd[2338]: Starting niri.service - A scrollable-tiling Wayland compositor... niri[2474]: 2025-08-29T04:07:40.043402Z INFO niri: starting version 25.05.1 (0.0.git.2345.d9833fc1) (...) niri[2474]: 2025-08-29T04:07:40.690512Z INFO niri: listening on Wayland socket: wayland-1 niri[2474]: 2025-08-29T04:07:40.690520Z INFO niri: IPC listening on: /run/user/1000/niri.wayland-1.2474.sock niri[2474]: 2025-08-29T04:07:40.700137Z INFO niri: listening on X11 socket: :0 systemd[2338]: Started niri.service - A scrollable-tiling Wayland compositor. $ echo $DISPLAY :0出现listening on X11 socket: :0且$DISPLAY已被正确导出即代表自动集成工作正常。为什么不用 Xwayland 而用 xwayland-satelliteniri 选择 xwayland-satellite 而不是直接内嵌 Xwayland官方 FAQ 给出了明确理由见 FAQ.md#why-doesnt-niri-integrate-xwayland-like-other-compositors集成 Xwayland 工作量巨大合成器需要实现大量 X11 窗口管理器逻辑X11 的窗口模型全局坐标系、窗口层级与 niri 的滚动平铺模型没有全局坐标概念本质冲突X11 的 bug 无穷无尽会不断吞噬维护精力如今纯 X11 客户端已经不多xwayland-satellite 足以覆盖绝大多数xwayland-satellite 把处理 X11 怪癖的大部分脏活揽了过去让 niri 只管理正常的 Wayland 窗口并与行为异常的客户端隔离。xwayland-satellite 与绝大多数应用兼容良好Steam、游戏、Discord甚至像 Ardour wine Windows VST 插件这类更冷门的组合。例外是那些试图把窗口或面板定位到特定屏幕坐标的 X11 应用它们在 xwayland-satellite 里行为会不正确需要借助嵌套合成器来运行见下文各节。二、源码视角集成到底发生了什么自动集成并非魔法其核心逻辑位于 src/utils/xwayland/satellite.rs 与 src/utils/xwayland/mod.rs主要分三步1. 启动阶段探测与建连niri 在启动时调用xwayland::satellite::setup()见 src/main.rs。setup()会依次执行读取配置取config.xwayland_satellite若off为真则直接跳过见 satellite.rs探测二进制调用test_ondemand()以:0 --test-listenfd-support参数运行 xwayland-satellite验证其支持按需激活satellite.rs。探测失败会打印警告并禁用集成创建 X11 连接setup_connection()在/tmp/.X11-unix下创建套接字从:0起扫描空闲 display写锁文件PID 格式为%10d\n并绑定抽象套接字Linux 专属与 unix 套接字见 mod.rs。2. 监听 X11 套接字按需拉起setup_watch()为抽象套接字与 unix 套接字各注册一个事件源一旦有 X11 客户端接入READ事件立即从事件循环中移除对应监听并调用spawn()启动 xwayland-satellite把 display 名作为参数传入satellite.rs。子进程环境会清掉DISPLAY、RUST_BACKTRACE等变量避免干扰satellite.rs。3. 崩溃自动重启spawn_and_wait()在一个独立线程线程名Xwl-s Spawner中等待 xwayland-satellite 退出无论正常退出还是崩溃都会向主循环发送ToMain::SetupWatch消息重新注册套接字监听——这就实现了xwayland-satellite 死了就自动重启的循环satellite.rs。代码中还专门用clear_out_pending_connections()清空套接字上积压的连接规避卫星启动失败导致的忙循环问题satellite.rs。4. 导出 DISPLAY集成成功后niri 会把 display 名如:0写入CHILD_DISPLAY并设置DISPLAY环境变量使所有派生的子进程都能看到src/main.rs。三、xwayland-satellite配置块控制集成行为xwayland-satellite是 niri 配置KDL 格式中的顶层选项自 25.08 起可用完整参数说明见 Configuration:-Miscellaneous.md#xwayland-satellite。键类型默认值作用off标志关禁用集成niri 不再创建 X11 套接字也不设置DISPLAY环境变量path字符串xwayland-satellitexwayland-satellite 二进制路径默认按普通程序名在$PATH中查找配置示例使用自定义构建的 xwayland-satellite// 使用自定义构建的 xwayland-satellite。 xwayland-satellite { path ~/source/rs/xwayland-satellite/target/release/xwayland-satellite }对应的解析实现位于 niri-config/src/misc.rsXwaylandSatellite结构体默认off: false、path: xwayland-satellite配置块还支持on标志用于在 include 合并场景中显式取消前面片段设置的offself.off | part.off; if part.on { self.off false; }并且path支持~展开在 satellite.rs 中处理。打包时请将xwayland-satellite列为运行 X11 应用Steam、Discord 等的必需依赖见 Packaging-niri.md。四、运行 X11 应用的多种嵌套方案如果某些 X11 应用如按屏幕坐标定位窗口/面板的程序在 xwayland-satellite 下行为异常或你想获得更传统的窗口管理体验niri 提供以下嵌套方案。方案一在 labwc Wayland 合成器里运行Labwc 是一个带 Xwayland 的传统堆叠式 Wayland 合成器可以当作 niri 的一个窗口运行再在其中运行 X11 应用从发行版软件源安装 labwc在 niri 内用labwc命令启动它会作为一个新窗口打开在 labwc 提供的 X11 DISPLAY 上运行 X11 应用例如env DISPLAY:0 glxgears。方案二直接以 rootful 模式运行 Xwayland该方法直接调用 Xwayland将其作为独立窗口运行并需要在其中额外运行一个 X11 窗口管理器直接运行Xwayland不带任何参数的裸二进制。会弹出一个黑色窗口你可以调整大小必要时用ModShiftF全屏。较老版本的 Xwayland 窗口可能是屏幕大小且不可缩放在其中运行 X11 窗口管理器例如env DISPLAY:0 i3从而管理 Xwayland 实例内的 X11 窗口运行 X11 应用例如env DISPLAY:0 flatpak run com.valvesoftware.Steam。在全屏 Xwayland 里运行全屏游戏几乎就是正常的游戏体验。[!TIP] 如果不运行 X11 窗口管理器每当所有 X11 窗口关闭、又有新窗口打开时Xwayland 都会关闭并重新打开它的窗口。要避免这一点请按上述方式在内部启动一个 X11 WM或打开某个长期运行的 X11 窗口。剪贴板注意事项目前 rootful Xwayland 似乎无法与合成器共享剪贴板。文本数据可以借助 wl-clipboard 手动中转env DISPLAY:0 xsel -ob | wl-copy从 Xwayland 复制到 niri 剪贴板wl-paste -n | env DISPLAY:0 xsel -ib从 niri 复制到 Xwayland 剪贴板。也可以绑定成快捷键binds { ModShiftC { spawn sh -c env DISPLAY:0 xsel -ob | wl-copy; } ModShiftV { spawn sh -c wl-paste -n | env DISPLAY:0 xsel -ib; } }方案三用 xwayland-run 运行专用 Xwaylandxwayland-run 是用于在专用 Xwayland rootful 服务器中运行单个 X11 客户端的辅助工具。它负责启动 Xwayland、设置 X11DISPLAY环境变量、配置 xauth并运行指定的 X11 客户端当 X11 客户端退出时xwayland-run 会自动关闭对应的专用 Xwayland 服务器。用法xwayland-run Xwayland 参数 -- 你的-X11-应用 X11 应用参数示例以 800x600 全屏运行 wine 游戏xwayland-run -geometry 800x600 -fullscreen -- wine wingame.exe方案四用 Cage 嵌套 Wayland 会话Cage 是一个 kiosk 风格的嵌套 Wayland 合成器同样支持 Xwayland可用于运行 X11 应用。相比 rootful Xwayland它无需额外运行 X11 窗口管理器一条命令即可cage -- /path/to/application。但要注意Cage 面向 kiosk 场景每次新窗口都会自动全屏并接管之前打开的窗口若在 Cage 内同时启动多个窗口可能会互相干扰。操作步骤安装cage大多数发行版仓库中都有运行cage -- /path/to/application即可在 niri 中体验你的 X11 程序。可选优化修改应用的 desktop entry给Exec属性加上cage --前缀。例如 Spotify Flatpak[Desktop Entry] TypeApplication NameSpotify GenericNameOnline music streaming service CommentAccess all of your favorite music Iconcom.spotify.Client Execcage -- flatpak run com.spotify.Client Terminalfalse方案五Proton-GE 原生 Wayland 运行游戏部分游戏可以以原生 Wayland 客户端运行从而绕开 X11 相关的问题。使用自定义版 Proton 如 Proton-GE在游戏的启动参数中设置PROTON_ENABLE_WAYLAND1环境变量即可。注意目前该功能属于实验特性并非所有游戏都支持且可能伴随自身的问题。PROTON_ENABLE_WAYLAND1 %command%方案六用 gamescope 运行 X11 游戏gamescope 是 Valve 出品的游戏会话微合成器可以用来运行 X11 游戏甚至 Steam 本身。与 Cage 类似gamescope 只显示单个、置顶的窗口不适合运行常规应用但你可以把 Steam 跑在 gamescope 里再从 Steam 正常启动游戏gamescope -- flatpak run com.valvesoftware.Steam全屏运行 gamescope 时可传入分辨率参数和全屏标志gamescope -W 2560 -H 1440 -w 2560 -h 1440 -f -- flatpak run com.valvesoftware.Steam[!NOTE] 如果 Steam 在 gamescope 中异常终止后续的 gamescope 调用有时会无法正常启动 Steam。若出现这种情况请先按上文方案二在 rootful Xwayland 中运行一次 Steam 并正常退出之后 gamescope 即可恢复使用。五、方案对比与选择建议方案是否需要 X11 WM单命令启动适用场景注意事项xwayland-satellite默认否是自动绝大多数 X11 应用Steam、Discord、游戏、wine 插件按坐标定位窗口/面板的应用不兼容labwc 嵌套否自带否需要传统堆叠式窗口管理体验需额外安装 labwcrootful Xwayland是如 i3否全屏游戏、需要完整 X11 环境剪贴板不共享需 wl-clipboard 手动中转xwayland-run否专用单客户端是单个 X11 客户端如 wine 游戏客户端退出即关闭 XwaylandCage否是kiosk 式单窗口 X11 应用多窗口互相全屏抢占gamescope否单窗口是游戏与 SteamSteam 异常退出后需重置六、延伸阅读相关配置完整说明Configuration:-Miscellaneous.md#xwayland-satellite为什么 niri 不内嵌 XwaylandFAQ.md#why-doesnt-niri-integrate-xwayland-like-other-compositors发行版打包时对 xwayland-satellite 的依赖要求Packaging-niri.md集成核心源码src/utils/xwayland/satellite.rs、src/utils/xwayland/mod.rs配置解析实现niri-config/src/misc.rs其他已知应用兼容性问题Application-Issues.md【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
