界面一片空白 cc-switch

Quick fix

升级 cc-switch 到最新版本以默认禁用 DMABUF 渲染，或改用 CLI 版本解决 Tauri 2 兼容性导致的白屏问题。

Symptom

报错原文复制

界面一片空白

Cause

cc-switch 从 3.7 版本开始使用了 Tauri 2，其对系统版本的要求相对较高。在较旧的系统（如 Debian 13.2 或 macOS 11.6）上，WebKit 的 DMABUF 渲染器会导致图形界面无法渲染，表现为界面一片空白或 CSS 未渲染。此外，早期版本在每次启动时会重置快捷方式配置，导致用户手动添加的环境变量失效。

Fix

1. 1

   升级 cc-switch 到最新版本。维护者已调整写入逻辑，默认将 WEBKIT_DISABLE_DMABUF_RENDERER=1 写入环境变量，并修复了快捷方式被重置的问题。

2. 2

   如果操作系统版本过低无法正常运行图形界面，建议改用 CLI 版本的 cc-switch-cli。

3. 3

   在 Linux 系统上，可以通过修改快捷方式文件，在启动命令前添加环境变量来临时解决渲染问题。

Affected Versions

Toolcc-switch

Version3.7.0 - 3.7.1

PlatformsLinuxmacOS

Source Issues

本页汇总自 2 个真实 issue

• #282从3.7版本在debian 13.2上不显示图形界面
• #292V3.7.1 UI没办法渲染

FAQ

修改快捷方式添加环境变量后，为什么重启又失效了？

旧版本的 cc-switch 每次启动都会将快捷方式配置重置为原始值。请升级到最新版本，该问题已修复且程序会默认自带环境变量配置。

在 macOS 11.6 上尝试了 3.3 到 3.5 版本依然无法渲染怎么办？

这是由于系统版本过低不满足 Tauri 2 的要求，建议升级操作系统，或者直接使用 cc-switch-cli 命令行版本。

相关问题

本地代理开关 UI 组件被截断，无法完全显示升级 cc-switch 至最新版本以修复窗口缩放导致的 UI 截断及托盘菜单溢出问题。1 issues mergedis not a model this version of Claude Code设置环境变量 CLAUDE_CODE_MAX_CONTEXT_TOKENS 或在模型名后追加 [1m] 以指定正确的上下文窗口大小。3 issues merged点击任意输入框后，界面卡死设置环境变量 WEBKIT_DISABLE_COMPOSITING_MODE=1 或升级至 v3.14.1 开启原生标题栏，可修复 Linux 下的界面卡死与按钮无响应问题。2 issues merged