如何用本站排查 cc-switch 问题

遇到 cc-switch 问题时，最快的方法不是先搜索一段自己概括的话，而是复制终端、日志或弹窗里的原始报错。

1. 从报错原文开始

把完整报错粘到首页搜索框。Pagefind 索引的是页面中的纯文本症状、问题标题和正文，因此像状态码、文件路径、环境变量以及 content[].thinking 这类字段都能直接命中。

如果没有明确报错，可以改用三个入口：

• 按报错码查：适合 HTTP 状态码、异常名和固定报错短语。
• 按供应商查：适合 DeepSeek、GLM、Kimi、通义千问、Copilot 等接入问题。
• 安装与启动：适合装不上、打不开、白屏、闪退或终端找不到命令。

2. 先确认 Symptom

主题页会先显示原始症状。逐字对照你的输出，尤其检查：

• 报错码是否相同；
• 文件名和路径是否相同；
• 使用的是 Claude Code、Codex 还是其他客户端；
• 操作系统和 cc-switch 版本是否落在页面列出的范围。

症状相似不代表根因相同。对不上时，不要直接执行 Fix。

3. 再读 Cause

Cause 解释为什么这个问题会发生。它通常能帮你判断故障位于供应商 API、本地代理、配置同步、客户端缓存还是操作系统环境。

理解这一层能避免“删库、重装、清空全部配置”这类代价很大的试错。

4. 一次只做一个 Fix

按页面顺序执行修复，每做一步就重新测试。修改配置前先备份原文件，并保留可以回滚的副本。不要同时更换供应商、端点、模型和代理设置，否则无法判断是哪一步生效。

5. 回到 Source Issues 核对

本站每个主题页都会列出真实 GitHub issue。修复步骤与当前版本不一致、页面标注问题仍未解决，或者你的场景有明显差异时，请打开 Source Issues 阅读维护者回复和后续评论。

只出现过一次但已有讨论的问题，还可以在更多已解决的问题中查找。