跳转到内容
CC Switch WikiUnofficial Community Wiki

Could not create default EGL display: EGL_BAD_PARAMETER cc-switch 白屏

Quick fix

Linux 下 cc-switch 强制 WEBKIT_DISABLE_DMABUF_RENDERER=1 导致白屏，预设该变量为 0 再启动即可恢复；点击失效/卡死另有对应变体解法。

Symptom

Section titled “Symptom”
报错原文
CC Switch.desktop[29046]: Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...

Cause

Section titled “Cause”

cc-switch 的 `src-tauri/src/main.rs` 在 Linux 上（用户未预设时）无条件设置 `WEBKIT_DISABLE_DMABUF_RENDERER=1` 和 `WEBKIT_DISABLE_COMPOSITING_MODE=1`。这套规避针对的是旧 NVIDIA / 旧 WebKitGTK 时代的 DMA-BUF 渲染器问题，但在 WebKitGTK 2.52 + Mesa 26（如 AMD amdgpu）环境下，DMABUF 被禁用后 WebKit 回退的 EGL 路径初始化直接失败，WebProcess 启动即 abort（`Could not create default EGL display: EGL_BAD_PARAMETER`），WebView 无内容、主窗口纯白。`HardwareAccelerationPolicy::Never` 只影响网页内容加速策略，挡不住 WebKit 自身的 EGL 初始化，所以无效。

同一套环境变量干预还衍生出两个变体：其一（#4350，3.16.2，Wayland + NVIDIA），AppImage 构建钩子 `apprun-hooks/linuxdeploy-plugin-gtk.sh` 无条件 `export GDK_BACKEND=x11`，强制 XWayland 后 webview 内容区完全收不到指针事件（GTK 标题栏正常）、resize 黑屏，此时 DMABUF 相关变量治不了输入失效；其二（#7059，3.20.1，X11 + fcitx5 + 混合显卡），点击"添加 → 自定义"时 WebKitWebProcess 卡死，且在该 NVIDIA 组合下把 DMABUF 设为 0 又会触发白屏，纯环境变量没有两全解。另有用户在 WSL2/WSLg（WebKitGTK 2.52.6、Mesa 26.0.3）下复现窗口空白但 WebView 子窗口坍缩为 `1x1+-1+-1`，设置 0 的规避方式无效，该变体目前无解。各 issue 的触发条件不同，但都与 cc-switch 对 WebKitGTK 渲染环境变量的无条件干预直接相关。

Fix

Section titled “Fix”

  1. 主窗口纯白（EGL abort，#6514）：在会话环境中预设 `WEBKIT_DISABLE_DMABUF_RENDERER=0`，应用尊重外部预设不会覆盖，启动后主界面恢复正常。已验证对 AppImage 与 deb 原生包均有效。

    /etc/environment（或写入会话环境）
    WEBKIT_DISABLE_DMABUF_RENDERER=0

  2. 若上述无效且版本在 3.19.x，可降回 3.16.3（#6514 报告者确认 3.16.3 正常，问题自 3.19.0 起出现）。

  3. Wayland + NVIDIA 下 webview 内容区点击失效、resize 黑屏（#4350，与 DMABUF 无关）：解包 AppImage，把钩子 `apprun-hooks/linuxdeploy-plugin-gtk.sh` 中的 `GDK_BACKEND=x11` 改为 `GDK_BACKEND=wayland`，再运行解包后的 `AppRun`。注意：自行解包重打包会破坏 Tauri updater 对 AppImage 的签名，故推荐直接运行解包目录而非重新打包。

    AppImage 解包目录内 apprun-hooks/linuxdeploy-plugin-gtk.sh 第 9 行
    export GDK_BACKEND=x11
    export GDK_BACKEND=wayland

  4. X11 + fcitx5 下点击"添加 → 自定义"整窗卡死（#7059）：以 `GTK_IM_MODULE=gtk-im-context-simple QT_IM_MODULE=simple XMODIFIERS=@im=none` 启动 cc-switch，绕过 fcitx5 与 WebKitGTK 2.40+ 的输入卡死；代价是窗口内无法用 fcitx5 输入中文。

  5. 长期修复方向（issue 中已建议、维护进展未知）：应用层提供可覆盖的环境变量开关（如 #4350 提议的 `CC_SWITCH_GDK_BACKEND`，已附 PR），或仅在检测到 NVIDIA 时才设置 `WEBKIT_DISABLE_DMABUF_RENDERER=1`。

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version受影响范围 3.19.0 - 3.20.4（3.16.3 正常；另 #4350 的 GDK_BACKEND 变体见于 3.16.2）
PlatformsLinux

Source Issues

Section titled “Source Issues”

本页汇总自 3 个真实 issue

FAQ

Section titled “FAQ”
WSL2 / WSLg 下设置 WEBKIT_DISABLE_DMABUF_RENDERER=0 后 WebView 仍然坍缩（1x1）不显示，有没有修复或 workaround？
目前没有。该变体（WSL2 / Ubuntu 24.04 / WSLg，WebKitGTK 2.52.6、Mesa 26.0.3，cc-switch 3.20.4）在 #6514 评论中被报告：日志无 EGL_BAD_PARAMETER，仅 WSLg 启动时 Xwayland glamor 回退软件渲染，设置 0 及叠加 GDK_BACKEND=x11、LIBGL_ALWAYS_SOFTWARE=1 均无效，尚无对应解法。
把 AppImage 解包改完钩子再重新打包分发可以吗？
不建议。#4350 明确指出构建后解包重打包会破坏 Tauri updater 对 AppImage 的签名，因此临时绕过应直接运行解包后的 `AppRun`，长期方案是让应用层提供可覆盖 GDK_BACKEND 的开关（该 issue 已附 PR）。
禁用 DMABUF 是为了修 NVIDIA 的问题，设为 0 会不会让 NVIDIA 用户白屏？
会，这正是 #7059 的矛盾点：在 X11 + 混合显卡（Intel + NVIDIA RTX 5070 Ti）组合下，`WEBKIT_DISABLE_DMABUF_RENDERER=0` 会触发 #6514 同款白屏（EGL abort），而默认的 1 又会在 fcitx5 下点击"自定义"卡死，该环境下纯环境变量暂无两全解。

相关问题

Section titled “相关问题”
输入框无法获得焦点/无法输入 OpenCode当前没有已确认的修复方案；该问题在 Linux Wayland 与 NVIDIA 环境下进入编辑页后会卡死。1 issues mergedThere's an issue with the selected model使用 NVIDIA NIM / MiniMax 时，开启本地代理并接管 Claude，同时开启整流器以过滤 prompt_cache_key 参数，或手动 export ANTHROPIC_BASE_URL 指向本地代理端口。2 issues mergedBash(...) Waiting... Claude Code降级 Claude Code 至 v2.1.104 或 v2.0.64（需管理员权限），或切换至阿里云百炼等兼容 provider，因 Nvidia 模型无法正确解析 tool use 格式。1 issues merged

这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。