主窗口完全空白(纯白) - CC Switch
Quick fix
设置环境变量 WEBKIT_DISABLE_DMABUF_RENDERER=0 以恢复 WebKitGTK 2.52 + Mesa 下的正常渲染。
Symptom
Section titled “Symptom”主窗口完全空白(纯白),托盘、代理、数据库等其余功能正常。在 Linux 环境下，cc-switch 的 `src-tauri/src/main.rs` 代码中无条件强制设置了 `WEBKIT_DISABLE_DMABUF_RENDERER=1`（除非用户已预设）。这一设置最初是为了规避旧版 NVIDIA 显卡或旧版 WebKitGTK 时代的 DMA-BUF 渲染器崩溃问题。
然而，在现代环境（如 WebKitGTK 2.52.3 + Mesa 26 + AMD/Intel GPU）下，DMABUF 渲染路径实际上是健康的。当应用强制禁用 DMABUF 后，WebKit 会回退到 EGL 路径进行初始化，但在新版驱动和库组合下，该回退路径会直接失败并导致 WebProcess abort（报错：`Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...`）。WebProcess 死亡后，WebView 无法加载内容，从而导致主界面呈现纯白空白状态。注意，应用内的“禁用硬件加速”选项仅影响网页内容渲染策略，无法阻止 WebKit 底层的 EGL 初始化崩溃。
在启动 cc-switch 之前，将环境变量 `WEBKIT_DISABLE_DMABUF_RENDERER` 设置为 `0`。这会让应用尊重外部预设，不再强制覆盖为 `1`，从而允许 WebKit 使用正常的 DMABUF 渲染路径。
Affected Versions
Section titled “Affected Versions”Source Issues
Section titled “Source Issues”本页汇总自 2 个真实 issue
- 为什么设置 WEBKIT_DISABLE_DMABUF_RENDERER=1 会导致主窗口变白？
- 因为该设置禁用了现代 Linux 发行版（如 Ubuntu 26.04）上 WebKitGTK 2.52+ 的健康渲染路径。禁用后，WebKit 尝试使用 EGL 回退路径初始化时发生致命错误（abort），导致渲染进程退出，界面因此空白。
- 我在应用设置里关闭了硬件加速，为什么还是不行？
- 应用内的“禁用硬件加速”配置仅针对网页内容的渲染策略生效，它无法阻止 WebKit 底层引擎在启动时对 EGL/DMABUF 渲染器的初始化检查。必须通过环境变量 `WEBKIT_DISABLE_DMABUF_RENDERER=0` 来修复底层的初始化崩溃。
- 这个问题只发生在 AMD 显卡上吗？
- 虽然 Issue #6514 报告的是 AMD (amdgpu) 环境，但该问题的根源在于新版 WebKitGTK 与 Mesa 对 EGL 回退路径的处理方式。任何运行 WebKitGTK 2.52+ 且 Mesa 较新的 Linux 用户（包括 Intel 或特定 NVIDIA 配置）若遇到此空白页问题，均可通过此方法解决。
这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。