启动失败 / 白屏排查

你会遇到什么

双击/命令行启动 cc-switch 无反应、白屏或闪退。三个常见根因：运行库缺失（webkit 等，见依赖条目）、配置损坏（~/.cc-switch/config.json 与版本不兼容）、共享配置被改写（~/.claude.json / ~/.codex/config.toml 段结构不匹配）。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

cc-switch 是 Tauri 桌面应用：缺 GUI 库 → 起不来；它管理 ~/.claude.json 的 provider 段和 ~/.codex/config.toml，这些共享文件被其它工具改过结构时，它按旧结构解析就白屏/闪退。终端启动看 stderr 是最快的定位方式。

桌面应用启动是“依赖链 → 配置加载 → 界面渲染”三段：缺共享库（webkit/gtk 等）时，动态链接阶段直接失败——表现为“双击没反应”（连进程都起不来）；配置损坏或结构不匹配时，进程起来了但解析失败——GUI 框架初始化不出内容，表现为“白屏/闪退”。

这两个失败点的差异就是定位线索：完全无反应 = 先查依赖（ldd | grep "not found"），起来但白屏 = 先查配置。

还有个隐藏风险面：~/.claude.json 这类文件是多工具共享的，其它工具按自己的结构改写后，cc-switch 按旧结构解析就崩——所以它只改 provider 段、不碰插件注册段，这是“写面最小化”的设计。终端启动保留 stderr 是最高效的定位方式，因为报错信息直接点名是缺库还是解析失败。

实测环境：无 GUI 库环境二进制不可运行（如实标注）；管理面 = ~/.cc-switch/config.json + ~/.claude.json + ~/.codex/config.toml（二进制字符串审计）。

一步步来

1. 依赖自查 — 必做

ldd /usr/bin/cc-switch | grep "not found"

有输出 → 缺库，sudo apt install -f 或按依赖条目补装。

2. 配置备份后重建 — 必做

mv ~/.cc-switch ~/.cc-switch.bak && cc-switch

启动正常后把要的配置从 .bak 迁回。

3. 终端启动看报错 — 排查

cc-switch

保留 stderr 输出，报错会直接指向根因（缺库/配置解析失败）。

4. 检查共享配置段 — 排查

python3 -m json.tool ~/.claude.json >/dev/null && echo JSON-OK

JSON 不合法 → provider 段被写坏；cc-switch 只改 provider 段，不碰插件注册段，恢复备份或手动修正。

怎么确认修好了

cc-switch --version && cc-switch

版本能输出、GUI 正常打开即成功（依赖补全后不再闪退）。

其它环境的表现

症状

双击/命令行启动无反应、白屏、或闪退。

原因

1. 运行库缺失（webkit 等，见症状 1）；
2. ~/.cc-switch/config.json 损坏或与版本不兼容；
3. 共享配置被其它工具改写（~/.claude.json / ~/.codex/config.toml 段结构不匹配）。

解法

1. 依赖自查：ldd /usr/bin/cc-switch | grep 'not found'——有输出说明缺库，apt 补装。
2. 配置备份后重试：备份 ~/.cc-switch/ 后删除让其重建。
3. 终端启动看报错：cc-switch（保留 stderr 输出）。
4. 共享配置段异常：检查 ~/.claude.json 的 provider 段 JSON 合法性（cc-switch 只改 provider 段，不碰插件注册段）。