3 Linux 图形问题

原文链接: https://tauri.app/develop/debug/linux-graphics/

在 Linux 上，Tauri 通过 WebKitGTK 渲染。在某些环境下（最常见的是 NVIDIA GPU），WebKitGTK 与显卡驱动无法达成一致，你会遇到从空白窗口到细微渲染问题等各种现象。本页汇总了已知症状与变通办法。原始报告见 tauri-apps/tauri#9394。

常见症状

• 窗口打开后一直空白或全白。
• 窗口闪烁，尤其是在调整大小时。
• 调整大小时应用崩溃，且没有有用的错误输出。
• 控制台显示 AcceleratedSurfaceDMABuf was unable to construct a complete framebuffer。
• 控制台显示 Gdk-Message: Error 71 (Protocol error) dispatching to Wayland display.

这些问题大多源自 WebKitGTK 的 DMABUF 渲染器请求了 NVIDIA 驱动并不提供的缓冲区格式。上游讨论见 WebKitGTK bug 跟踪器和 NVIDIA 论坛。

变通办法

请按顺序尝试。越靠前的方法越能保留硬件加速。

1. 确保内核模式设置（KMS）已开启。早于 545 的 NVIDIA 驱动通常需要把 nvidia_drm.modeset=1 作为内核参数。
2. 设置 __NV_DISABLE_EXPLICIT_SYNC=1。这通常能在没有性能损失的情况下修复 Wayland 的 Error 71 崩溃。
3. 设置 WEBKIT_DISABLE_DMABUF_RENDERER=1。能修复 DMABUF framebuffer 错误和 Error 71 崩溃，代价是失去更快的渲染路径。
4. 设置 WEBKIT_DISABLE_COMPOSITING_MODE=1。这是调整大小时静默崩溃的最后手段。它会完全禁用加速合成。

你可以在 shell 中设置这些变量来测试，也可以在创建 webview 之前的 main() 中设置，这样用户就不必自己设置：

1
2
3
4
5
6
7
8

fn main() {
  // 针对 NVIDIA 上 WebKitGTK 的变通办法，见 tauri-apps/tauri#9394
  #[cfg(target_os = "linux")]
  std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");

  tauri::Builder::default()
    // ...
}

只有在你确认自己的应用确实受影响时，才应当发布这种无条件的覆盖设置。它会让所有人（包括环境正常的用户）失去一条更快的路径。

静默失败：WebGL 与 canvas

并非所有问题都会崩溃或报错。WebGL 与 canvas 内容可能悄悄落到慢路径上，而应用其它部分看起来一切正常。有两件事让你很难从前端内部发现这一点：

• 即使结果由软件光栅化器或缓慢的呈现路径支撑，WebGL2 上下文创建也会成功。没有错误可以捕获。
• WebKitGTK 出于指纹防护会掩盖 WebGL 渲染器字符串。WEBGL_debug_renderer_info 在每台 Linux 机器上都报告 Apple GPU，因此你无法检查上下文背后究竟是什么。

实践中，这表现为 WebGL 密集视图（终端模拟器、编辑器、地图、图表）中输入延迟高或帧率低，而同样的代码在普通浏览器里很快。如果你的应用有 WebGL 渲染路径，请在 Linux 上为它提供非 WebGL 的降级方案，并考虑暴露一个设置让用户切换，而不要指望上下文能告诉你实情。