error code is 2503 或升级后图标变白 - CC Switch

Quick fix

修改 per-user-main.wxs 移除快捷方式 Icon="ProductIcon" 属性即可解决安装失败与升级后图标丢失问题；旧版用户需取消固定后重新固定。

Symptom

报错原文复制

The installer has encountered an unexpected errorinstalling this package. This may indicate a problem withthis package. The error code is 2503.

Cause

该问题源于 CC Switch 3.19.0 的 WIX MSI 打包配置缺陷。模板 src-tauri/wix/per-user-main.wxs 中的桌面与开始菜单快捷方式均设置了 Icon="ProductIcon"，强制 Windows Installer 将图标提取至 %APPDATA%\Microsoft\Installer\{ProductCode}\ 缓存目录。

由于构建使用 Product Id="*" 每次生成新 ID，且启用了 MajorUpgrade（升级即先卸载旧版），旧缓存目录会在升级时被清空。新安装时路径解析或权限冲突会直接抛出错误代码 2503；而任务栏固定的 .lnk 文件不受 MSI 组件更新机制保护，重启后系统重建图标缓存，因原路径文件已不存在，故显示为空白默认图标。

Fix

1. 1

   打开项目源码中的 src-tauri/wix/per-user-main.wxs 文件，定位到桌面快捷方式定义行。

   src-tauri/wix/per-user-main.wxs

   <Shortcut Name="CC Switch" Directory="DesktopFolder" Icon="ProductIcon" ... />
   <Shortcut Name="CC Switch" Directory="DesktopFolder" ... />

2. 2

   删除文件中另一处开始菜单快捷方式的 Icon="ProductIcon" 属性，保存后重新执行构建命令生成新的 MSI 安装包。

3. 3

   已安装旧版的用户请右键点击任务栏上的空白图标选择“从任务栏取消固定”，随后重新运行新版 MSI 完成升级，再次将应用固定到任务栏即可恢复。

Affected Versions

Toolcc-switch

Version3.19.0

PlatformsWindows

Source Issues

本页汇总自 2 个真实 issue

• #5929最新的3.19版本,似乎无法安装
• #5949[Windows] MSI 升级后，任务栏固定图标在重启电脑后变为空白

FAQ

为什么 NSIS 安装包（setup.exe）不受影响？

NSIS 安装程序不依赖 Windows Installer 的 ProductCode 机制管理快捷方式图标，因此不会在升级时误删图标缓存文件。

修复发布后，已经损坏的任务栏图标会自动恢复吗？

不会。该修复仅能防止新版本出现此问题。已受影响用户的 .lnk 文件内已写死失效路径，必须手动“取消固定 → 重新固定”一次才能读取到新 exe 的正确图标。

相关问题

codex cli 失败：CC Switch将 cc-switch 升级至 v3.16.3 或更高版本即可修复本地环境检测与升级链路的阻塞问题。2 issues merged无法安装和更新 Codex CC Switch升级到 v3.16.3+ 后从「设置 → 关于」重新安装/更新 Codex；若 v3.16.5 仍失败请带日志反馈。2 issues merged在Codex界面，官方订阅无法查询用量 - Codex开启本地路由映射以统计特定模型用量，第三方API需适配查询脚本，Claude官方及Free账号暂不支持查询。8 issues merged