cc-switch 启动闪退 / 白屏 / 黑屏 / 后台崩溃
Quick fix
升级到最新版；Windows 白屏安装 WebView2，代理崩溃改端口并升级 v3.9.1+，旧 macOS/Linux 用 CLI 或对应发行版包。
Symptom
Section titled “Symptom”3.9版本开启代理后，只要claude cli发起请求，ccs先是界面卡死然后就闪退了，关闭代理后就正常了。该集群包含多种不同机制的启动或运行期崩溃。第一类是开启本地代理后，请求处理发生 panic，典型原因是代理层截断日志或请求体时切到多字节字符边界，例如 byte index 2000 is not a char boundary，此类问题在 v3.9.1 的 Proxy Panic Prevention / graceful degradation 中修复。第二类是 Windows 白屏或闪退，通常与 WebView2 缺失、旧系统版本、签名拦截或后续版本 UI/标题栏问题有关；v3.2.0 和 v3.9.0+ 分别修复了部分白屏/黑屏问题。第三类是 Windows 后台运行时出现 tao 事件循环断言或状态错误，例如 flush_paint_messages 或 cannot move state from Destroyed，issue 中未给出明确最终修复版本。第四类是 macOS/Linux 白屏、卡死或无法启动，多与 Tauri 2 对系统、WebKit/GTK、硬件加速或安装包类型要求较高有关；旧 macOS 和某些 Linux 环境建议使用 cc-switch-cli 或对应发行版安装包。另有端口冲突导致代理开关异常或崩溃的情况，例如 7890 与 Clash 冲突，或端口 5000 被建议改为 15721。
先升级 cc-switch 到最新版本。开启代理后闪退的问题已在 v3.9.1 修复，Windows 黑屏问题在 v3.9.0+ 通过切换系统标题栏修复，维护者建议升级到 v3.12.3 验证。
如果开启本地代理后 Claude Code / Codex / Gemini CLI 发起请求时 cc-switch 卡死或闪退，关闭代理验证；确认与代理相关后升级到 v3.9.1 或更新版本。若端口为 5000，可尝试改为 15721；若端口为 7890 且与 Clash 冲突，更换其他端口。
Windows 打开白屏时，确认系统已安装 WebView2 Runtime；若彻底卸载过 Edge，可能缺少 WebView2，可安装 WebView2RuntimeInstaller.exe 后重试。
Windows 白屏/闪退且升级无效时，删除用户目录下的 .cc-switch 文件夹，卸载后重装；若仍异常，可备份数据后清空相关文件再重装。
如果从 v3.9.* 降级到 v3.8.3 后崩溃，需要恢复之前备份的 cc-switch.db；否则建议直接使用新版本而不是降级。
Linux 白屏、卡死或无法启动时，优先使用 v3.9.0+ 提供的对应发行版安装包；Fedora 可测试 rpm 包。若在 VMware 中白屏，关闭虚拟机硬件加速。
macOS 版本过旧（如 macOS 10.15 Catalina 或 macOS 11）出现白屏、无法启动或提示不支持时，Tauri 2 对系统和 WebKit 版本要求较高，可改用 cc-switch-cli：https://github.com/SaladDay/cc-switch-cli
Windows 因错误配置 WSL 路径等原因无法启动时，可用 Geek Uninstaller 等工具彻底卸载，并清理 C:\Users\<用户名>\AppData\Local\com.ccswitch.desktop 目录后重装；重要数据先备份。
如果后台运行偶发崩溃，收集 .cc-switch/log 或 .cc-switch/logs 下的日志提交给维护者；该集群中部分 tao 事件循环崩溃未给出明确修复版本。
Affected Versions
Section titled “Affected Versions”Source Issues
Section titled “Source Issues”本页汇总自 20 个真实 issue
- #17window11 运行失败，程序闪退
- #26最新版本 v3.2.0 在 macOS Sequoia 15.6.1 运行闪退
- #119Ubuntu24 LTS 安装打开后白屏
- #347Mac 版本打不开了
- #381This software does not run on macOS versions older than Big Sur
- #414windows24H下，3.8.x-3.9-x版本打开都黑屏，几秒后闪退，降级到3.7.x 版本恢复正常
- #465v3.8.3打开就崩溃，系统mac 26.2
- #490AppImage 在 Ubuntu KDE 桌面环境下，输入框输入任意内容后程序卡死并崩溃
- #537Fedora 43 Linux 上无法启动
- #553win11开启代理后闪退
- #568使用本地代理导致 APP 直接 Crash
- #669Windows11自己退出进程问题
- #719mac电脑直接主界面白屏
- #768app后台运行的时候，有时候会崩溃，日志如下
- #1027MAC 11.7.10 安装后打开白屏，如何解决
- #1226Windows11无法正常启动
- #1415windows11环境下经常闪退
- #1585MacOS启动白屏
- #1608Windows 11 环境下配置 CC Switch 为 WSL 的Claude 路径后无法启动的
- #1718代理总开关打不开
- 开启代理后才闪退，关闭代理就正常，是什么原因？
- 这是代理层处理请求时发生 panic 导致，常见于 v3.9 附近版本。升级到 v3.9.1 或更新版本可修复；同时避免与 Clash 等工具端口冲突，必要时把端口从 5000 改为 15721 或更换 7890。
- Windows 打开一直是白屏怎么办？
- 先安装或修复 WebView2 Runtime，尤其当 Edge 被卸载过时。再升级到 v3.2.0 或更新版本；若仍无效，删除用户目录下的 .cc-switch 并重装。
- Mac 老系统提示不支持或打开白屏怎么办？
- Tauri 2 对 macOS 和 WebKit 版本要求较高，macOS 10.15/11 等旧版本可能无法正常渲染。可改用 cc-switch-cli：https://github.com/SaladDay/cc-switch-cli
- Linux 白屏或输入后卡死怎么办？
- 使用 v3.9.0+ 提供的对应发行版安装包，例如 Fedora 可试 rpm 包；VMware 用户可关闭硬件加速。AppImage/Flatpak 在某些环境下仍可能失败。
- 从 v3.9.* 降级到 v3.8.3 后崩溃怎么办？
- 用过 v3.9.* 后降级需要恢复之前备份的 cc-switch.db；否则建议升级到新版本而不是降级。
- 后台运行一段时间后自己退出，日志里有 tao 错误，怎么解决？
- 这类崩溃与 Windows 事件循环有关，issue 中未给出明确最终修复版本。建议升级到最新版，若仍复现，提交 .cc-switch/log 或 .cc-switch/logs 下的日志。
这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。