mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-21 03:40:31 +08:00
bbed2a1fe1
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
4.7 KiB
4.7 KiB
5.2 常见问题 FAQ
安装问题
macOS 提示「未知开发者」
问题：首次打开时提示「无法打开，因为它来自身份不明的开发者」
解决方法一：通过系统设置
- 关闭警告弹窗
- 打开「系统设置」→「隐私与安全性」
- 找到 CC Switch 相关提示
- 点击「仍要打开」
- 再次打开应用
解决方法二：通过终端命令（推荐）
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
执行后即可正常打开应用。
Windows 安装后无法启动
可能原因：
- 缺少 WebView2 运行时
- 杀毒软件拦截
解决方法：
- 安装 Microsoft Edge WebView2
- 将 CC Switch 添加到杀毒软件白名单
Linux 启动报错
问题：AppImage 无法启动
解决方法：
# 添加执行权限
chmod +x CC-Switch-*.AppImage
# 如果仍然失败，尝试
./CC-Switch-*.AppImage --no-sandbox
供应商问题
切换供应商后不生效
原因：CLI 工具需要重新加载配置
解决方法：
- Claude Code：关闭并重新打开终端，或重启 IDE
- Codex：关闭并重新打开终端
- Gemini：托盘切换可即时生效，无需重启
API Key 无效
检查步骤：
- 确认 API Key 正确复制（无多余空格）
- 确认 API Key 未过期
- 确认端点地址正确
- 使用速度测试验证连接
如何恢复官方登录
操作步骤：
- 选择「官方登录」预设（Claude/Codex）或「Google 官方」预设（Gemini）
- 点击「启用」
- 重启对应的 CLI 工具
- 按照 CLI 工具的登录流程操作
代理问题
代理服务启动失败
可能原因：端口被占用
解决方法：
- 检查端口占用：
# macOS/Linux lsof -i :49152 # Windows netstat -ano | findstr :49152 - 关闭占用端口的程序
- 或尝试修改配置恢复默认端口：
- 打开「设置 → 代理服务」
- 点击「恢复默认」按钮
代理模式下请求超时
可能原因：
- 网络问题
- 供应商服务器问题
- 代理配置错误
解决方法：
- 检查网络连接
- 尝试直接访问供应商 API（关闭代理）
- 检查供应商配置是否正确
关闭代理后配置未恢复
可能原因：代理异常退出
解决方法：
- 编辑当前供应商
- 检查端点地址是否正确
- 保存以更新配置
故障转移问题
故障转移没有触发
检查清单：
- 代理服务是否运行
- 应用接管是否开启
- 自动故障转移是否开启
- 队列中是否有备用供应商
频繁触发故障转移
可能原因：
- 主供应商不稳定
- 熔断器阈值设置过低
解决方法：
- 检查主供应商状态
- 调高失败阈值（如从 3 改为 5）
- 考虑更换主供应商
所有供应商都熔断了
解决方法：
- 等待熔断时长到期（默认 60 秒）
- 或重启代理服务重置状态
数据问题
配置丢失
可能原因：
- 配置目录被删除
- 数据库损坏
解决方法：
- 检查
~/.cc-switch/目录是否存在 - 从备份恢复：
~/.cc-switch/backups/ - 或从之前导出的配置文件导入
导入配置失败
可能原因：
- 文件格式错误
- 版本不兼容
解决方法：
- 确认文件是 CC Switch 导出的 JSON 文件
- 检查文件内容是否完整
- 尝试用文本编辑器打开检查格式
用量统计数据为空
检查清单：
- 代理服务是否运行
- 应用接管是否开启
- 日志记录是否开启
- 是否有请求通过代理
其他问题
托盘图标不显示
macOS：
- 检查系统设置中的菜单栏图标设置
Windows：
- 检查任务栏设置，确保 CC Switch 图标未被隐藏
Linux：
- 需要安装系统托盘支持（如
libappindicator）
界面显示异常
解决方法：
- 尝试切换主题（浅色/深色）
- 重启应用
- 删除
~/.cc-switch/settings.json重置设置
更新失败
解决方法：
- 检查网络连接
- 手动下载最新版本安装
- 如使用 Homebrew：
brew upgrade --cask cc-switch
获取帮助
提交 Issue
如果以上方法都无法解决问题：
- 访问 GitHub Issues
- 搜索是否有类似问题
- 如果没有，创建新 Issue
- 提供以下信息：
- 操作系统和版本
- CC Switch 版本
- 问题描述和复现步骤
- 错误信息（如有）
日志文件
提交 Issue 时可附上日志文件：
- macOS/Linux：
~/.cc-switch/logs/ - Windows：
%APPDATA%\cc-switch\logs\