CC Switch 启动失败时该退出还是自救：两套渲染树

桌面应用启动期最难写的一段，往往不是错误提示的措辞，而是那个决定：出了这个错，还要不要继续把界面渲染出来。渲染出来，用户至少有个地方能操作；不渲染直接退出，能保证不在一个半坏的状态上继续写数据。这两种做法各有各的道理，难点在于分清哪种错该走哪条路。

CC Switch 的入口文件 src/main.tsx 把这个决定摊开写了：同一个文件里有两处根渲染，一处是完整的应用，一处是精简过的恢复界面；再往上还有一条根本不渲染、直接结束进程的路。三条路的判据都在源码里，可以逐行读出来。

先说清这篇文章的依据

本文对应的仓库快照是 3217f725，仓库内版本号 3.20.1，核对日 2026-08-31。我们只做静态源码阅读：没有编译、没有打包、没有安装过这个桌面应用，也没有触发过任何一次真实的启动失败。所以下面出现的一切都是「代码里是这么写的」，不是「跑起来是这样的」。凡涉及界面呈现、动画观感、耗时长短，一律不在本文讨论范围内。

入口文件的执行顺序

src/main.tsx 是个一百多行的单文件入口。它做的事按顺序排开：

:28 是模块顶层的一行 installGlobalErrorHandlers()——注意它在任何 React 渲染之前执行，实现落在 src/lib/frontendLogger.ts:325-345，注册的是全局 error 与 unhandledrejection 监听。放在这个位置的意义很直白：比 React 还早发生的崩溃也得有人接住，否则错误边界根本没机会挂上。

:31-40 读 navigator.userAgent 与 navigator.platform 判断 macOS，命中就给 document.body 加一个 is-mac class，整段包在 try/catch 里，catch 里的注释写「忽略平台检测失败」——平台探测失败不该拦住启动。

:80-86 订阅后端事件 configLoadError。

:88 开始的 bootstrap() 是异步函数，:155 结尾一句 void bootstrap(); 把整个启动流程踢出去，void 显式吞掉这个 promise——配合前面那对全局 handler，未捕获的拒绝仍有人记录。

同一个错误，为什么要查两遍

配置加载失败这件事，代码里有两条获取路径：:80-86 的事件订阅是一条，bootstrap() 一进来就 invoke("get_init_error") 主动拉一次是另一条。:89 的注释把理由写死了：「启动早期主动查询后端初始化错误，避免事件竞态」。

这句话值得单独拎出来。前端订阅事件和后端 emit 事件之间存在一个时间窗，后端如果在前端 listen 注册完成之前就把错误发出去了，这条事件就丢了，而丢掉的恰好是「你为什么起不来」这类最需要被看见的信息。补法不是加延迟，是加一条不依赖时序的主动查询。两条路径都指向同一个处理函数，谁先到算谁的。

第一种收场：读不出配置就退出

:54-76 的 handleConfigLoadError 只做两件事——弹一个 Tauri 原生对话框，然后 await exit(1) 结束进程。函数上方 :50-53 的注释交代了取舍：「不给用户”取消”选项，因为配置损坏时应用无法正常运行」。

这是一条彻底的 fail-fast。它的合理性在于这个工具的职责本身：它要读写本机上真实的 CLI 配置文件，配置源都读不出来还继续渲染，等于让这个应用在没有配置底数的前提下工作，此后任何一次保存都可能把残缺状态写回真实的配置文件，覆盖掉本来还好好的东西。宁可退出，也别在残缺状态上写。

一个细节值得 Windows 侧读者注意：:57 那句 payload?.path ?? "~/.cc-switch/config.json" 里的字符串只是兜底占位。后端 payload 带了 path 就用后端给的，没带才用这一串。也就是说这行代码不能当作「配置文件在哪」的依据，它只是错误文案里的一个填充值。

bootstrap() 里 :108-112 也走这条路：initError 带了 path 或 error 字段就直接调它，后面还跟一行注释「不会执行到这里，因为 exit(1) 会终止进程」——那个 return 是写给类型检查和读代码的人看的。

第二种收场：数据库版本过新时，换一棵树

真正有意思的是 :94-107 这一支。判据只有一个：initError.kind === "db_version_too_new"。命中之后，它渲染的是这样一棵树，渲染完直接 return，根本不进 <App />：

StrictMode
  └─ FrontendErrorBoundary
       └─ ThemeProvider
            ├─ DatabaseUpgrade
            └─ Toaster

对照 :120-133 的正常分支：

StrictMode
  └─ FrontendErrorBoundary
       └─ QueryClientProvider
            └─ ThemeProvider
                 └─ UpdateProvider
                      ├─ App
                      └─ Toaster

两棵树的差集就是两层：QueryClientProvider 和 UpdateProvider。恢复分支一层都不要。

这个删减不是随手写的。React Query 在这个项目里承担的是全部后端数据面，src/lib/query/queryClient.ts:3-14 的全局默认是 retry: 1、refetchOnWindowFocus: true、staleTime: 0，也就是说只要挂上它，任何一次重新挂载或窗口聚焦都会去后端重新取数据。而此刻的前提恰恰是「后端的库应用读不懂」。让一个专门用来解释这件事的界面，去依赖那个已经出问题的数据面，逻辑上就不通。这三个是 v3.20.1 的默认配置，可配，也会随版本变。

UpdateProvider 被砍掉的道理略有不同，但同样是硬约束：src/contexts/UpdateContext.tsx:144-150 的 useUpdate() 在没有 Provider 时是直接 throw new Error("useUpdate must be used within UpdateProvider") 的。这条规则反过来给恢复分支划了一道边界——这棵树底下的组件一旦碰 useUpdate()，就不是「拿不到更新信息」而是当场崩掉。少挂一层 Provider，等于把一整类可能的崩因排除在恢复路径之外。theme-provider.tsx:148-154 的 useTheme() 是同一套写法，而 ThemeProvider 恰恰被保留了下来，恢复界面才敢用它。

保留下来的三层同样各有理由。StrictMode 两边一致，没有为了「省事」在异常路径上换一套开发期检查。FrontendErrorBoundary 是 class 组件（React 错误边界只能用 class），:17-19 的 getDerivedStateFromError 置 hasError，:21-27 的 componentDidCatch 调 reportFrontendError("react.error_boundary", ...)，:34-64 的崩溃兜底里唯一的动作是 window.location.reload()（:56）。它在两棵树里都是最外层的错误捕获层（StrictMode 之内、其余 Provider 之外）——恢复分支自己再崩，下面还剩一层地板。ThemeProvider 与 Toaster 保留，则是因为恢复界面也得有主题和消息通道。

恢复界面自己也有分支

src/components/DatabaseUpgrade.tsx 这个组件把恢复过程切成了五个阶段，类型定义是 type Phase = "checking" | "upgradable" | "incompatible" | "updating" | "error"。文件里的注释写明了分流：有可用更新，就走一键下载、安装、重启这条路；已经是最新版本、数据库却仍然过新，就判为 incompatible，并明确告诉用户升级解决不了这个问题。

incompatible 这一档是这段代码里最诚实的部分。绝大多数「版本过旧」的处理都止步于「请升级」，而这里承认了一种升级也没用的情况——数据库可能由更高版本或别的客户端写过，当前这个版本的应用就是读不懂。同一个文件里还硬编码了一个 RELEASES_URL 常量指向项目自己的 releases 页，给的是去处，不是保证。

第三种：既不退出也不换树

启动期还有一类异常走的是第三档。:135-152：syncModelsDevPricingOnStartup() 是在正常渲染之后才被调用的，成功且未跳过才去失效 ["usage"] 和 MODELS_DEV_SYNC_CONFIG_QUERY_KEY 两个查询。:147 的 catch 注释说得很清楚：处于离线状态、或者那个外部数据源暂时不可用，都不应该阻塞应用启动——失败只上报错误，仍然失效同步配置查询，应用照常往下跑。

顺带一提 :118 的 initializeWindowActivity()，它被放在正常渲染之前、恢复分支之后：恢复分支在 :107 就 return 了，压根走不到这一行。

把三档并排看，分级标准就浮出来了：

异常	处置	界面	源码位置
配置文件读不出来	exit(1)，不给取消	只有原生对话框	main.tsx:50-76、:108-112
数据库版本过新	换一棵精简渲染树	恢复界面，不挂 Query 与 Update 两层	main.tsx:94-107
联网增强项失败	只上报，不阻塞	正常应用	main.tsx:135-152

判据其实是同一个问题问了三遍：这个错误会不会让”继续操作”变成一件危险的事？ 会——退出；不会但当前功能确实不可用——换一个专门解释这件事的界面；不会且只影响一个增强能力——记下来，接着跑。

一个可以自己复核的动作

不需要装应用也能验证上面的结构：打开仓库里的 src/main.tsx，数一下 ReactDOM.createRoot 出现了几次，再看这两次 render 各自包了哪几层 Provider。差异一眼可见，也不会因为读者的环境不同而变。

版本口径上还有一条值得记：把 v3.19.2 与 v3.20.1 的 src/main.tsx 做 diff，增删行数是 0，两个版本都是 155 行，一行没动。同期 src/App.tsx 从 1740 行涨到 1829 行、有三百多个增删行。src/contexts/UpdateContext.tsx、src/components/theme-provider.tsx、src/lib/query/queryClient.ts 在这两版之间同样是零改动。启动链路这一层在这次迭代里是被当作稳定件对待的——但这只是这两个版本之间的对比，不构成对后续版本的任何预期。

---

本文依据 CC Switch 官方仓库（github.com/farion1231/cc-switch）的 README、docs/ 下的用户手册、 路由指南与发布说明，以及 src/、src-tauri/、tests/ 的源码整理， 核对日 2026-08-31，对应仓库快照 3217f725（仓库内版本号 3.20.1）。 本文内容为仓库源码与文档口径，我们没有安装或运行过这个桌面应用， 因此不涉及界面外观、操作手感与切换速度的任何描述。 文中出现的阈值与默认值均为源码中的默认配置，不构成对实际运行结果的保证。 该项目仍在快速迭代，版本与默认值随时可能变动，请以仓库最新内容为准。 安全相关做法请结合自身环境评估，本文不构成安全方案建议。