cc-switch 升级失败、卡死或花屏问题排查

Quick fix

升级 cc-switch 到最新版本（v3.16.3+ 修复了更新卡死问题，v3.20.0+ 支持 winget 安装的 Claude Code，v4.0 重构了升级流程）；winget 安装的 Claude Code 需用 winget 命令手动升级。

Symptom

报错原文复制

在cc-switch gui界面中，设置→关于中，3.16.1版本能看到winget安装的Claude code但是升级失败，手动升级winget安装的Claude code并升级cc-switch到3.16.3之后，看不见Claude code了

Cause

该问题集群包含多个与升级和 UI 相关的故障。首先，cc-switch 在 v3.16.1 至 v3.16.3 期间无法正确识别通过 winget 安装的 Claude Code（路径为 %LOCALAPPDATA%\Programs\claude），导致升级失败或升级后无法显示，因为早期版本仅支持 npm 安装方式，v3.20.0 起才支持 winget 检测，v4.0 进一步优化了对非 npm 安装的原生程序的升级提示。其次，macOS 用户在点击更新时界面会卡住，强制关闭后才发现已更新，这是因为旧版本的下载-安装-重启流程依赖 WebView 在应用包被替换后继续运行 JS，存在死锁问题，该问题在 v3.16.3 通过将流程移至后端执行（install_update_and_restart）修复。此外，还存在 Windows 上的花屏问题（可能与硬盘损坏后的重装有关，4.0 版本重构了相关功能）、Ubuntu 系统上编辑供应商时界面卡死（v4.0.11 重构 UI 后引入的 bug），以及 macOS 在线升级后 Dock 栏显示双份图标（v4.0.10-v4.0.12）等问题。

Fix

1. 1

   升级 cc-switch 到最新版本（建议 v4.0 或更高），以获取 winget 安装检测、更新流程优化及 UI 重构修复

2. 2

   对于 winget 安装的 Claude Code，使用 winget 命令手动升级：winget upgrade Claude.Code（或参考 Claude Code 官方文档）

3. 3

   若遇到 macOS 更新卡住，确保使用 v3.16.3 或更高版本，更新流程已改为后端执行，无需强制关闭

4. 4

   若问题仍存在（如 Ubuntu 编辑卡死、Dock 双图标），在 GitHub issue 中反馈，附上 cc-switch 版本、系统版本、安装路径和报错信息

Affected Versions

Toolcc-switch

Version3.16.1 - 4.0.12（部分问题在 v3.16.3、v3.20.0 或 v4.0 修复）

PlatformsWindowsmacOSLinux

Source Issues

本页汇总自 5 个真实 issue

• #4212cc-switch对于winget管理的Claude code会升级失败
• #4318mac系统在点击更新时一段时间会卡住，然后强制关闭重新打开发现已经更新到最新版本了
• #4328显示花屏
• #8302ubuntu26系统，重构UI的版本全部存在编辑供应商时界面卡死的bug
• #8329在线升级后dok栏显示双份图标

FAQ

为什么 cc-switch 看不到我 winget 安装的 Claude Code？

在 v3.20.0 之前，cc-switch 仅支持 npm 安装的 Claude Code。请升级到 v3.20.0 或更高版本，并确保 Claude Code 安装在 %LOCALAPPDATA%\Programs\claude 路径下。

macOS 上点击更新后界面卡住怎么办？

这是 v3.16.3 之前版本的已知问题，因更新流程依赖 WebView 导致死锁。请升级到 v3.16.3 或更高版本，更新流程已移至后端执行。

升级后 cc-switch 界面花屏或卡死（如 Ubuntu 编辑供应商时）如何解决？

花屏问题可能与系统环境有关，建议升级到 v4.0 或更高版本（重构了相关功能）。Ubuntu 编辑卡死是 v4.0.11 的已知 bug，请关注 GitHub issue #8302 的修复进展。

macOS 在线升级后 Dock 栏显示两个图标怎么办？

这是 v4.0.10 至 v4.0.12 版本的已知问题，请关注 GitHub issue #8329 的修复进展，或尝试重新安装 cc-switch。

相关问题

codex cli 失败：CC Switch将 cc-switch 升级至 v3.16.3 或更高版本即可修复本地环境检测与升级链路的阻塞问题。2 issues mergedCodex接入第三方模型，对话经常自动中断根因是 cc-switch 把 Codex 的 Responses API 工具调用转成上游 Chat Completions 时丢失了 function call 的 name/call_id；可让 DeepSeek 直连 Codex 绕过代理，或升级 cc-switch 后复测。7 issues merged官方账号突然不显示余量信息 Codex升级到包含 4.0 额度显示重做的最新版复测；若仍不显示，请提供版本、登录方式、套餐类型和日志。3 issues merged