跳转到内容
CC Switch WikiUnofficial Community Wiki

cc-switch 检查更新失败 / 更新安装失败

Quick fix

更新失败多因权限不足或 GitHub 网络异常；请用管理员/绿色版安装，或到 GitHub Releases 手动下载。

Symptom

Section titled “Symptom”
报错原文
windows的cc-switch检查更新失败

Cause

Section titled “Cause”

该集群包含多个与更新/升级相关但根因不同的问题：

1. 启动时自动检查更新可能因为 GitHub 网络、updater manifest、签名清单或插件环境失败，旧版本会把“检查更新失败”作为用户可见错误弹出，即使用户已经是最新版。后续版本已改为自动检查失败不再打断用户，手动检查失败时降级打开 GitHub 最新发布页。 2. Windows 安装/更新到 C:\Program Files\CC Switch 等受保护目录时，如果安装器没有管理员权限，会因目标目录无写入权限导致更新失败或安装失败。维护者建议改用不需要权限的 LocalAppData 默认安装目录、管理员模式、绿色版或 CLI 版。 3. Linux 覆盖安装新版本后，软件内版本号可能仍显示旧版本，这是安装覆盖后版本信息未正确更新的问题，卸载后重新安装可恢复。 4. macOS 上通过 brew tap farion1231/ccswitch 可能提示 MacOSVersionError；issue 记录显示该问题已在后续版本清理中被覆盖，但未给出具体机制。 5. 工具管理面板中 Hermes 的“最新版本”可能低于本地已安装版本，因为检测来自 PyPI，而 Hermes 主线已迁移到 git/GitHub releases 分发，PyPI 发布滞后。该问题与 cc-switch 自身更新失败不同，属于第三方工具版本源不一致。

Fix

Section titled “Fix”

  1. 如果 Windows 更新或安装失败，先确认安装目录是否为 C:\Program Files\CC Switch 等需要写入权限的目录。若是，请卸载后重新安装到不需要权限的 LocalAppData 默认目录，或使用绿色版/CLI 版。

  2. 如果必须安装到受保护目录，请用管理员模式运行安装器。

  3. 如果启动时提示“检查更新失败”，但你已经是最新版本，升级到包含修复的 cc-switch 版本；新版本不会再把自动检查更新失败作为用户可见错误挂出来。

  4. 如果手动点击“检查更新”失败，直接打开 GitHub Releases 页面确认并下载最新版本，不要依赖内置 updater。

  5. 如果 Linux 覆盖安装后软件内版本号仍显示旧版本，完全卸载当前版本后重新安装新版本。

  6. 如果 Hermes 显示“最新版本 < 当前版本”，这是 PyPI 版本检测滞后导致；请以 GitHub Releases / git tag 为准，或等待 cc-switch 改用 GitHub Releases API 检测。

Affected Versions

Section titled “Affected Versions”
Toolcc-switch
Version未知
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

本页汇总自 17 个真实 issue

FAQ

Section titled “FAQ”
我已经是最新版本，为什么还提示检查更新失败？
旧版本会把启动时自动检查更新的失败直接显示给用户，可能由 GitHub 网络、updater manifest、签名清单或插件环境问题触发。后续版本已修复为自动检查失败不再弹出用户可见错误。
Windows 安装最新版本失败怎么办？
通常是目标目录没有写入权限。请用管理员模式打开安装器，或者使用绿色版/CLI 版，也可以卸载后重装到不需要权限的 LocalAppData 默认目录。
更新没有提权管理员导致更新失败，msi 跑完进度条后消失，重新打开还是旧版本，怎么处理？
维护者说明默认安装目录已改为不需要权限的 LocalAppData 目录。可以卸载旧版本后重新安装，数据不会丢失。
覆盖安装后软件内版本号仍显示旧版本怎么办？
这是 Linux 覆盖安装后版本信息未正确更新的问题。临时解决方案是完全卸载后重新安装。
macOS 执行 brew tap farion1231/ccswitch 提示 MacOSVersionError 怎么办？
该 issue 已在后续版本清理中被关闭，维护者表示问题已修复或被最新版本覆盖。如果新版本仍可复现，请带版本号、系统环境、复现步骤和日志反馈。
Hermes 最新版本显示 0.19.0，但本地已安装 0.20.4，是 cc-switch 更新坏了吗？
不是 cc-switch 自身更新失败。Hermes 的最新版本检测来自 PyPI，而 Hermes 主线已迁移到 git/GitHub releases 分发，PyPI 滞后，所以出现最新版本低于当前版本。请以 GitHub Releases / git tag 为准。
能不能关闭 Claude Desktop 自动更新？
该集群中的相关 issue 是功能请求：希望在设置页增加 Claude Desktop 的 disableAutoUpdates 开关，用于关闭或恢复 Claude Desktop 自动更新。该 issue 仍处于 open/stale 状态，未确认已实现。

相关问题

Section titled “相关问题”
codex升级为ChatGPT后不适配了吗 cc-switch升级到 cc-switch v3.17.0，该版本已适配 Codex 合并到 ChatGPT Desktop 后的供应商切换，避免旧配置被覆盖。5 issues merged还没有添加任何供应商升级或云同步后 UI 状态与底层数据库不同步，完全重启应用或重新导入备份即可恢复供应商列表。5 issues merged重启后.claude下的auth.json会被强制替换 - Codex升级 cc-switch 至最新版，或在登录官方账号前先关闭代理接管，避免旧快照覆盖官方凭据。5 issues merged

这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。