跳转到内容
CC Switch WikiUnofficial Community Wiki

EGL_BAD_PARAMETER 白屏报错 cc-switch

Quick fix

改用 .deb 或 AUR 原生包安装，或通过 LD_PRELOAD 预加载系统库运行 AppImage 以解决 ABI 冲突。

Symptom

Section titled “Symptom”
报错原文
Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...

Cause

Section titled “Cause”

该问题源于 AppImage 内置的 WebKitGTK、GTK 或 GLib 库与宿主系统较新的显示服务器协议（Wayland/X11）、显卡驱动或系统库存在 ABI 冲突。当 WebKitGTK 尝试调用宿主系统的 Mesa/EGL 库创建默认显示时，由于参数或环境不匹配导致初始化失败，进而引发渲染进程挂起、界面白屏并抛出该错误。在较新发行版（如 Ubuntu 26.04）中，还会因打包的旧版 GLib 与宿主 GVFS 模块不兼容而伴随 GIO 模块加载失败。

Fix

Section titled “Fix”

  1. 改用原生包安装（推荐）：卸载 AppImage，使用 .deb 包或 AUR (cc-switch-bin) 安装。原生包直接调用宿主系统的 WebKitGTK 和 GLib 库，可彻底避免 ABI 冲突。

  2. 通过 LD_PRELOAD 预加载系统库：如果必须使用 AppImage，可在终端中预加载宿主系统的 Wayland 客户端库来绕过冲突，例如运行 LD_PRELOAD=/usr/lib/libwayland-client.so ./CC-Switch-v3.17.0-Linux-x86_64.AppImage。

  3. 使用 CLI 版本：若图形界面问题在当前发行版下仍无法解决，可改用无界面的命令行版本 cc-switch-cli。

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version3.8.3 - 3.19.0
PlatformsLinux

Source Issues

Section titled “Source Issues”

本页汇总自 6 个真实 issue

FAQ

Section titled “FAQ”
为什么在 Ubuntu 26.04 等较新系统上还会看到 undefined symbol: g_task_set_static_name 错误？
这是因为 AppImage 打包了较旧的 GLib/GIO 库，与宿主系统较新的 GVFS 模块存在 ABI 不兼容，改用 .deb 包即可解决。
使用 LD_PRELOAD 启动后感觉界面卡顿怎么办？
预加载系统库可能会带来额外的性能损耗，建议直接通过 AUR (cc-switch-bin) 或 .deb 包安装原生版本以获得最佳流畅度。

相关问题

Section titled “相关问题”
“event handler is re-entrant” 报错或启动闪退卸载 Windows 更新 KB5081263 或等待 cc-switch 升级以规避 TAO EventLoop 重入导致的崩溃与界面不渲染问题。2 issues mergedGtk-CRITICAL: gtk_widget_get_scale_factor 失败在 Linux 或 WSL2 中运行 cc-switch 遇到 GTK 断言失败时，请修改 settings.json 关闭静默启动，或清理残留配置重装。3 issues mergedWarmup request downgraded to model在 CC Switch 中关闭 Copilot 的 warmupDowngrade 选项，防止请求被静默替换为 gpt-5-mini。5 issues merged

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