CC Switch 在 Windows 上安装后无法启动怎么排查？

在 Windows（Windows 10 及以上，x64）上通过安装包或绿色版装好 CC Switch 后，可能出现双击无反应、进程起不来或窗口打不开的情况。这篇文档对应 安装指南 与 常见问题 FAQ 中「Windows 安装后无法启动」一节，给出文档列出的两类可能原因（缺少 WebView2 运行时、杀毒软件拦截）以及每一步之后的判断依据和验证方法，帮你按顺序定位卡在哪一环。

先确认安装是否真正完成

FAQ 把「缺少 WebView2 运行时」和「杀毒软件拦截」列为 Windows 安装后无法启动的两大可能原因。在排查这两项之前，先排除最基本的情况：安装程序本身没有跑完。

文档说明，运行 MSI 安装程序后如果没有任何反应，是 Windows 的安全机制阻断了从网络下载的可执行文件。处理方法是：

1. 在下载的安装包文件上点击右键，选择「属性」；
2. 在「常规」页的「安全」区域勾选「解除锁定」；
3. 关闭属性窗口后重新双击运行安装程序，按提示完成安装。

完成后再运行一次应用。这一步不需要命令行操作，判断标准很直接：勾选「解除锁定」之前安装程序静默无响应，解除后能正常走完安装向导，即说明这一环已解决。

另外注意安装渠道。安装指南 强调 CC Switch 只应从 ccswitch.io 官网、GitHub Releases 页或项目源码仓库获取，文件名形如 CC-Switch-v<版本号>-Windows.msi（<版本号> 按你实际下载的文件替换）；绿色版则是 CC-Switch-v<版本号>-Windows-Portable.zip，解压后运行其中的 CC-Switch.exe。绿色版不经过安装程序，如果绿色版同样无法启动，可以跳过卸载重装，直接进入下面两步。

检查一：安装 Microsoft Edge WebView2 运行时

CC Switch 的桌面窗口基于 WebView2 渲染，FAQ 明确指出「缺少 WebView2 运行时」是安装后无法启动的可能原因。

处理步骤：

1. 从微软官方渠道下载并安装 Microsoft Edge WebView2 运行时（安装指南和 FAQ 指向的即 Microsoft Edge WebView2 官方页面提供的运行时安装包）；
2. 安装完成后重新启动 CC Switch。

这一步的验证方式就是「验证安装」一节的标准结果：应用窗口正常显示、系统托盘出现 CC Switch 图标、应用切换器中能看到已启用的受管应用并能切换到目标应用面板。如果安装 WebView2 后应用正常打开，问题到此结束。

检查二：将 CC Switch 加入杀毒软件白名单

如果 WebView2 已安装（很多较新系统上自带），但应用仍然无法启动，FAQ 给出的第二个原因是杀毒软件拦截。

处理步骤：打开杀毒软件或安全软件，将 CC Switch 的可执行文件（安装目录下的主程序，绿色版则是解压目录中的 CC-Switch.exe）添加到信任列表/白名单，然后再次启动。

同样以窗口能否正常显示来判断。若杀毒软件把主程序隔离删除了，需要先从隔离区恢复文件再启动。

启动后看到白屏或「界面出错了」卡片

能启动但界面不正常时，区分两种现象：

• 白屏：按 v3.18.0 Release Notes 的说明，v3.18.0 起 React 错误边界会包住整个界面，渲染进程崩溃时显示「界面出错了」卡片和重载按钮，而不是只剩一片白屏，且前端崩溃会落盘留证。看到该卡片时点击「重载」；若你使用的版本低于 v3.18.0，可先升级，或在「设置 → 关于」中手动检查更新。
• 托盘图标不显示：FAQ「托盘图标不显示」一节说明，Windows 上应检查任务栏设置，确认 CC Switch 图标未被隐藏（可能被收入任务栏折叠区）。这属于图标可见性问题，不影响应用本体运行。

查看日志确认问题

上述步骤都无法解决时，查看 CC Switch 的日志目录。FAQ「日志文件」一节 给出的默认路径为：

• 普通错误、网络或代理问题：C:\Users\<用户名>\.cc-switch\logs\ 中的 cc-switch.log 及其轮转文件（运行日志按 20 MB 轮转，保留最近 4 个归档）；
• 应用崩溃：C:\Users\<用户名>\.cc-switch\crash.log 及 crash.log.1、crash.log.2。

如果你在高级设置中修改过配置目录，以自定义目录为准。注意日志可能包含运行环境信息，公开提交前建议先检查内容。

仍无法启动：提交 Issue

按 FAQ「获取帮助」一节，若以上方法都无法解决问题，到项目 Issues 页面先搜索是否有类似问题；没有则创建新 Issue，并提供以下信息：

• 操作系统和版本；
• CC Switch 版本；
• 问题描述和复现步骤；
• 错误信息（如有），并附上上一步取到的 cc-switch.log 或 crash.log。

小结与限制

排查顺序固定为：确认安装真正完成（必要时「解除锁定」重跑安装）→ 安装 WebView2 运行时 → 杀毒软件白名单 → 检查日志。每一步的判断依据就是应用窗口能否正常显示、托盘图标是否出现。文档只覆盖到 WebView2 缺失与杀毒拦截两类 Windows 启动失败原因；如果日志显示的是其他错误（例如数据库或迁移问题），则应带着日志提交 Issue，而不是继续猜测本机环境。