启动序列、崩溃日志、轻量模式与托盘：主进程都干了什么

2026-08-10

一个桌面应用「启动」听起来只是双击一下，但 cc-switch 的主进程在把窗口交出去之前，要按固定顺序跑完一长串动作：装 panic hook、注册插件、刷新配置目录覆盖、初始化日志、校验旧配置、建库迁移、按表做首启导入、装托盘。这串动作里有两处的正确性完全靠顺序——顺序换一下，用户就会从「可以重试」掉进「一次失败之后永远起不来」。

这篇只讲主进程这一层：src-tauri/src/lib.rs 的 run() 与 .setup()，加上围着它转的 panic_hook.rs、lightweight.rs、tray.rs、app_store.rs、auto_launch.rs、linux_fix.rs。数据库表结构、迁移调度、原子写入、Tauri 命令数各有专门篇目在讲，这里只引与启动直接相关的那几行。

以下全部基于我们本地 clone 的 cc-switch 仓库快照 c39c903（提交日期 2026-08-10），仓库内版本号 3.19.2。我们只读源码文本，没有安装也没有运行过这个桌面应用。

窗口出现之前的那一串

lib.rs 的 run() 加 .setup() 段落在 src-tauri/src/lib.rs:324-440，动作顺序是：

panic_hook::setup_panic_hook()
注册 single_instance 插件
注册 deep_link 插件
窗口关闭拦截
process / dialog / opener / store / window_state 四五个插件
进入 setup 后安装 rustls ring provider
刷新 app_config_dir 覆盖
初始化日志，落到 <app_config_dir>/logs/cc-switch.log

这个排法里有两个细节值得单独拎出来。panic hook 排在第一位，也就是说从这一行之后发生的任何 panic 都能被记下来；排在它前面的东西再出问题就没有记录可查了。日志初始化排在「刷新 app_config_dir 覆盖」之后，这一步的先后决定了 cc-switch.log 到底写进哪个目录——日志初始化排在覆盖刷新之后，日志文件的落点才跟着覆盖值走。

配置目录覆盖这件事本身在 app_store.rs（135 行）：覆盖值存在 Tauri Store 的 app_paths.json 文件里，key 是 app_config_dir_override，进程内用 OnceLock<RwLock<Option<PathBuf>>> 缓存；路径支持 ~、~/、~\ 三种前缀展开；如果覆盖路径不存在，代码只 warn 一句然后回退默认目录（app_store.rs:10-127）。默认目录是 ~/.cc-switch（src-tauri/src/config.rs:207）。

反直觉的那一处：两个「必须早于」

真正撑住启动流程的不是某个功能，是两处顺序约束。

第一处：旧 config.json 的校验必须早于创建数据库。 代码在 src-tauri/src/lib.rs:490-522：如果存在旧的 config.json 而数据库尚未建立，就先进一个 loop，反复尝试加载这份 JSON；加载失败弹对话框，用户选重试就再来一轮，用户选退出就 std::process::exit(1)。源码注释把这么写的理由说得很直白——此时数据库文件还没被创建，下次启动可以正常重试。

顺序若反过来（先建库、再校验 JSON），失败退出时磁盘上已经躺着一个空库；下次启动看到「有库」，迁移分支就不会再走，那份旧 config.json 里的数据就再也进不来了。这就是那种「读代码时觉得多此一举、想清楚才发现换不得」的地方。

第二处：数据库版本过新的预检必须早于任何 schema 写操作。 命中之后的处理也不一样：不是报错退出，而是写一个 InitErrorPayload{kind: "db_version_too_new"}、强制显示主窗口，然后直接 return Ok(())（lib.rs:530-556）。后面所有初始化步骤统统不跑。对应的错误文案在 src-tauri/src/database/schema.rs:421-427，是一句中文：「数据库版本过新（{version}），当前应用仅支持 {SCHEMA_VERSION}，请升级应用后再尝试。」当前的 SCHEMA_VERSION 是 16（src-tauri/src/database/mod.rs:54-56）。

放到实际场景里就是：你在两台机器上同步过 ~/.cc-switch/，一台装的是新版、另一台是旧版，旧版这台会走到这个分支。它选择「什么都不动」而不是「尽力而为地打开」，因为一旦让旧版应用去写新版 schema，库就可能被写坏。

数据库真正初始化那一步也在 loop 里跑，失败同样弹对话框让用户选重试或退出（lib.rs:557-572）。库可用之后紧接着做的第一件事是把持久化的日志级别应用上去，读取失败时显式 fail-closed 回退到 Info（lib.rs:574-591）——不是沿用上一档，而是回到一个确定值。

迁移与首启导入：按表独立，互不牵连

JSON 迁移成功之后，旧文件的处理方式是重命名成 config.json.migrated 而不是删除（lib.rs:600-607）。

首启导入那一段（lib.rs:625-960）值得注意的是它的判定粒度：默认 skill 仓库、Skills 的 SSOT 迁移、MCP 从各应用导入、提示词从各 AppType 的 live 文件导入，每一项各自判断、互不影响，其中 MCP 与提示词的导入条件都是「对应的表为空时才导」。所以某一项导入失败不会连累其它项，但反过来说，表一旦非空就不会再自动导第二次。

启动态本身也存了一份，在 init_status.rs（124 行）：用三组 OnceLock<RwLock<..>> 分别存初始化错误、JSON 迁移成功标记、Skills SSOT 迁移结果。后两者是**「取一次即消费」**语义，对应 take_migration_success 与 take_skills_migration_result。这个语义决定了这两个标记只能被拿走一次——前端拿到之后再问就没有了。

崩溃日志：文件、上限与那把锁

panic_hook.rs 共 300 行，作用是把 panic 写进 <app_config_dir>/crash.log。三个常量都在文件头部（panic_hook.rs:13-19）：

项	值
`CRASH_LOG_MAX_SIZE`	`5 * 1024 * 1024`（5 MB）
`CRASH_LOG_ARCHIVES_TO_KEEP`	2
版本号来源	`env!("CARGO_PKG_VERSION")`
写入串行化	`static CRASH_LOG_LOCK: Mutex<()>`

这张表按「一次崩溃要记什么、记多少、怎么不打架」来读：单文件到 5 MB 就轮换，归档只留 2 份，所以崩溃日志占用有上界；版本号取自编译期常量而不是运行时读配置，意味着崩溃现场即使配置读不出来也仍带得上版本；那把 Mutex<()> 是为了多线程同时 panic 时写入不互相踩。

要提醒一句：crash.log 落在应用配置目录里，而这个目录同时也放着数据库与设置。它是本机文件，你要把它发给别人排查之前，请自己先看一眼内容。这属于通用运维习惯，不是该项目文档里的要求。

轻量模式：真的把窗口销毁了

lightweight.rs 只有 100 行，但它做的事比名字听上去激进：用 static LIGHTWEIGHT_MODE: AtomicBool 记状态，进入轻量模式时销毁主窗口——不是隐藏。平台差异写在同一段里：Windows 上额外调 set_skip_taskbar(true)，macOS 上调 apply_tray_policy(app, false)（lightweight.rs:6-95）。

退出轻量模式时，代码先判断窗口是否已被销毁，若已销毁则用 WebviewWindowBuilder::from_config 按 main 窗口的配置重建一个。这也解释了为什么这个模式必须依赖托盘：窗口没了之后，托盘是仅剩的入口。

commands/lightweight.rs 对外只暴露 3 条命令（进入、退出、查询状态）——同一层里 provider.rs 是 30 条、proxy.rs 是 24 条，这个模块的对外面确实很窄。

托盘：ID 是 `cc-switch`，不是 `main`

tray.rs 有 1537 行，本篇只用其中两处。托盘 ID 是个常量：pub const TRAY_ID: &str = "cc-switch"（tray.rs:157），并且仓库里有测试专门断言它等于 "cc-switch" 且不等于 "main"（tray.rs:1139-1140）。为一个字符串常量写断言，说明这个值被别处按名字引用着，改名会断链。

另一处是托盘的用量刷新：图标的 Enter 与 Click 事件会异步刷新用量缓存，源码注释写明 refresh_all_usage_in_tray 内部有 10 秒防抖（lib.rs:1035-1046）。这个缓存就是 AppState 三个字段里的 usage_cache（src-tauri/src/store.rs:6-11），services/usage_cache.rs 的模块头注把它定义为「托盘展示用的用量缓存（进程内、写穿式）……不持久化」。所以托盘上那份数字是进程内的缓存值，进程一退就没了，10 秒内的重复触发也不会真去重算。

开机自启与 Linux 的那点特殊照顾

auto_launch.rs（117 行）用 auto_launch crate 的 AutoLaunchBuilder，app_name 固定为 "CC Switch"。里面有一段 macOS 专属处理：需要把 .app/Contents/MacOS/ 这样的可执行文件路径回溯成 .app bundle 路径，注释写明否则 AppleScript 的 login item 会去打开终端（auto_launch.rs:5-38）。

Linux 侧有两处。一处在 main.rs——这个文件全长只有 35 行，除了 Linux 的环境变量设置就只调用了一句 cc_switch_lib::run()（src-tauri/src/main.rs:33）；Linux 上默认设置 WEBKIT_DISABLE_DMABUF_RENDERER=1 与 WEBKIT_DISABLE_COMPOSITING_MODE=1，并留了逃生开关 CC_SWITCH_GDK_BACKEND（main.rs:9-31）。关于这个开关怎么用，我们另有一篇专门讲。

另一处是 linux_fix.rs（121 行），带 #[cfg(target_os = "linux")] 门控——lib.rs 顶部声明的 39 个模块里，只有它带平台门控（src-tauri/src/lib.rs:1-39）。它导出 nudge_main_window，做法是「显式 set_focus + 一次无视觉的 ±1px 伪 resize」来模拟最大化-还原。三个时序常量摆在一起（linux_fix.rs:23-40）：REALIZE_WAIT = 200ms、RESIZE_GAP = 100ms、RECONCILE_WAIT = 500ms，注释写明合计约 800ms 之后回读校验尺寸。这些是源码里的常量，不是我们观察到的表现——我们没有在任何桌面环境上运行过它。

你自己怎么核这一段

这些说法全都可以在半小时内自己走一遍，不需要装应用：

看启动主线：打开 src-tauri/src/lib.rs，从 :324 读到 :440 是插件与日志，lib.rs:490-522 的旧配置校验、:557-572 的建库循环、:600-607 的迁移收尾三段连着读。两处「必须早于」的注释就写在代码旁边，不用推测。
对两个错误分支：lib.rs:530-556 的 db_version_too_new 与 src-tauri/src/database/schema.rs:421-427 的中文错误文案，是同一件事的两端，比对着看能看清预检为什么要放在写 schema 之前。
数模块与门控：打开 src-tauri/src/lib.rs 顶部的模块声明块（lib.rs:1-39），其中带 #[cfg(target_os = "linux")] 的只有 linux_fix。
核常量：panic_hook.rs:13-19、tray.rs:157、linux_fix.rs:23-40 三处常量都在文件头部或靠前位置，直接跳行去看。
看那条测试：tray.rs:1139-1140 那个断言 TRAY_ID != "main" 的测试，是判断「这个常量是不是被别处按名字依赖」最省事的证据。

顺带记一处与本篇直接相关的口径差：README_ZH.md:561-568 的项目结构树只写了 commands/ services/ database/ proxy/ session_manager/ deeplink/ mcp/ 这几个目录，而本篇用到的 tray.rs、panic_hook.rs、lightweight.rs、auto_launch.rs、app_store.rs、init_status.rs、linux_fix.rs 全是 src-tauri/src/ 下的根级 .rs 文件，一个都没出现在那棵树里——这类根级文件实际有 30 多个。两处不一致就说到这里，谁对谁错、为什么没同步，我们不推断。

最后框一下边界。本篇引用的行号与常量全部来自静态阅读，没有编译、没有运行、没有跑过任何测试。tray.rs 我们只读了常量与函数签名，1537 行的主体没读；panic_hook.rs 后 240 行也没读。所以本文能说的只有「代码里是这么写的」，说不了「跑起来会怎样」。想知道启动到底卡在哪一步，最可靠的入口还是 <app_config_dir>/logs/cc-switch.log 与同目录的 crash.log——它们的位置就在上面那条启动序列的第 8 步里定好了。

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