Linux 图形问题

在 Linux 上，Tauri 通过 WebKitGTK 进行渲染。在某些配置下，通常是 NVIDIA GPU，WebKitGTK 与图形驱动程序不兼容，你可能会遇到从空白窗口到轻微渲染问题的各种情况。本页收集了已知的症状和解决方法。有关最初的报告，请参见 tauri-apps/tauri#9394。

🌐 On Linux, Tauri renders through WebKitGTK. On some setups, most often NVIDIA GPUs, WebKitGTK and the graphics driver disagree and you get anything from a blank window to subtle rendering problems. This page collects the known symptoms and workarounds. See tauri-apps/tauri#9394 for the original reports.

常见症状

🌐 Common symptoms

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

大多数情况是由于 WebKitGTK DMABUF 渲染器请求 NVIDIA 驱动程序不提供的缓冲区格式。有关上游讨论，请参阅 WebKitGTK bug 跟踪器和 NVIDIA 论坛。

🌐 Most of these come from the WebKitGTK DMABUF renderer requesting buffer formats the NVIDIA driver does not provide. See the WebKitGTK bug tracker and the NVIDIA forums for upstream discussion.

变通方法

🌐 Workarounds

按顺序尝试这些。较早的选项保留硬件加速。

🌐 Try these in order. The earlier ones keep hardware acceleration.

确保内核模式设置已开启。NVIDIA 545 之前的驱动程序通常需要将 nvidia_drm.modeset=1 作为内核参数。
设置 __NV_DISABLE_EXPLICIT_SYNC=1。这通常可以在不影响性能的情况下修复 Wayland 的 Error 71 崩溃。
设置 WEBKIT_DISABLE_DMABUF_RENDERER=1。修复 DMABUF 帧缓冲错误和 Error 71 崩溃，但代价是较快的渲染路径。
设置 WEBKIT_DISABLE_COMPOSITING_MODE=1。在调整大小时出现无声崩溃的最后手段。这会完全禁用加速合成。

你可以在你的 shell 中设置这些进行测试，或者在创建 webview 之前在 main() 中设置它们，这样用户就不必设置了：

🌐 You can set these in your shell to test, or set them in main() before the webview is created so users do not have to:

fn main() {
  // Workaround for WebKitGTK on NVIDIA, see tauri-apps/tauri#9394
  #[cfg(target_os = "linux")]
  std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");

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

只有在确认你的应用受到影响时，才发送这样的无条件覆盖。它会禁用所有人的更快路径，包括那些在正常设置下的用户。

🌐 Only ship an unconditional override like this if you have verified your app is affected. It disables a faster path for everyone, including users on working setups.

静默失败：WebGL 和画布

🌐 Silent failures: WebGL and canvas

并非每个问题都会导致崩溃或显示错误。WebGL 和画布内容可能会在后台悄悄走上慢路径，而应用的其余部分看起来一切正常。有两件事使得从前端内部很难检测到这一点：

🌐 Not every problem crashes or shows an error. WebGL and canvas content can silently land on a slow path while the rest of the app looks fine. Two things make this hard to detect from inside your frontend:

即使结果由软件光栅器或缓慢的呈现路径支持，WebGL2 上下文创建也会成功。没有错误可以捕获。
WebKitGTK 会屏蔽 WebGL 渲染器字符串以保护指纹识别。WEBGL_debug_renderer_info 在每台 Linux 机器上都报告 Apple GPU，因此你无法检查上下文背后实际的内容。

在实践中，这表现为在 WebGL 重负载视图（终端模拟器、编辑器、地图、图表）中输入延迟高或帧率低，而相同的代码在普通浏览器中运行得很快。如果你的应用有 WebGL 渲染路径，请在 Linux 上提供一个非 WebGL 的备用方案，并考虑提供一个设置，让用户可以切换，而不是依赖上下文告诉你。

🌐 In practice this shows up as high input latency or low frame rates in WebGL heavy views (terminal emulators, editors, maps, charts), while the same code is fast in a regular browser. If your app has a WebGL rendering path, give it a non WebGL fallback on Linux and consider exposing a setting so users can switch, instead of trusting the context to tell you.