CC Switch 环境检查卡住不动怎么排：子进程挂死的四个原因

「检查环境」这个动作发出去之后迟迟没有结束，是这类桌面工具最难办的一类问题：它没有报错，也就没有可以搜索的错误文案。CC Switch 的仓库里正好有一条专治这个的修复，把「为什么会永远等下去」拆得相当清楚——挂死的不是这个应用自己，而是它拉起来的那个子进程。

先说清楚这篇的依据。文中的行号、常量名与注释都来自 cc-switch 仓库 v3.20.1 的静态阅读，对应的仓库快照是 3217f725，核对日 2026-08-31。我们只读源码与 docs/ 下的文档，没有编译、没有运行、也没有安装过这个桌面应用，所以下面不会出现任何关于界面长什么样、按钮转多久的描述；症状的说法一律来自 commit message 与发布说明的原文。

第一步：先分清是哪一条「环境检查」

这个软件里有两块都可以叫「环境检查」，代码路径毫无交集，排查方向也完全相反。

一块是环境变量冲突检查，实现在 src-tauri/src/services/env_checker.rs:20-32。它做的事情是：按应用取关键词，在 Windows 上读 HKEY_CURRENT_USER\Environment 与 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment 两处注册表值（:66-101），在非 Windows 上读当前进程环境（:103-120）并逐行扫固定的几个 shell 配置文件（:123-173）。

另一块是「关于」面板里的 CLI 版本探测、安装冲突诊断与升级，实现集中在 src/components/settings/AboutSection.tsx，后端在 src-tauri/src/commands/misc.rs。手册 docs/user-manual/zh/1-getting-started/1.5-settings.md 里叫它「本地环境检查」——顺带一提，手册那张工具表比 AboutSection.tsx:62-71 的 TOOL_NAMES 短，两处口径不一致，按表对照会以为漏了工具；这里以我们实读的 v3.20.1 仓库状态为准。

判定动作很简单：会挂死的是第二块。 因为只有它需要为每个工具拉起真实的子进程去问版本，而第一块从头到尾是在读文件和读键值。如果停住的是环境变量那条，方向应该往权限和路径上找，而不是往下面这四件事上找。

挂死的四件事：进程组、控制终端、作业控制、超时

对应的修复是 fd14f9c4，标题 fix(env-check): stop upgrade/conflict preflight from hanging forever。这条提交的标题里没有 issue 编号，body 里点明它修的是 #5522 那次重构引入的回归。commit body 把成因说得很直白：安装冲突预检会 spawn 一个交互式 shell（zsh -lic），放进一个隔离的后台进程组、但仍然继承着控制终端；shell 因为作业控制被 SIGTTIN / SIGTTOU 自我停止，于是 child.wait() 永远不返回。

把这条链拆开就是四件事，缺一件都不会挂：

1. 进程组：子进程被放进了独立的后台进程组，kill(-pid) 的整组击杀语义因此成立。
2. 控制终端：只换进程组并不会脱离控制终端。父进程若是从终端启动的（比如开发模式），这个终端就被继承下去了。
3. 作业控制：一个持有控制终端、又处在后台进程组里的交互式 shell，会被作业控制信号停住——它不是崩了，是被暂停了。
4. 超时：以上三件凑齐只是「有可能停住」，真正让它变成永久挂起的是第四件——这条路径当时完全没有超时预算。

docs/release-notes/v3.20.0-zh.md:177 的补充值得单抄一遍：即便在不可能发生这种情况的场景下（正常启动的构建并没有控制终端），这条路径也完全没有超时，Windows 亦然。也就是说前三件是触发条件，第四件才是后果被放大成永久的原因。

v3.20.1 里这四件事分别怎么处理的

脱离终端。 src-tauri/src/commands/misc.rs:3074 的 isolate_child_process_group，把原来的 cmd.process_group(0) 换成了在 pre_exec 里调 libc::setsid()。:3077-3084 的注释解释了为什么这样换：新会话自带新进程组，terminate_child_tree 里 kill(-pid) 的整组击杀语义不变，但额外脱离了控制终端；shell 拿不到 /dev/tty 之后，作业控制自动关闭，也就不会再被停住。注释里还写了 SAFETY 依据：setsid 是 async-signal-safe，fork 出来的子进程必然不是组长，调用不会因 EPERM 失败。

关掉 stdin。 resolve_path_default 的 spawn 显式加了 .stdin(Stdio::null())（src-tauri/src/commands/misc.rs:2221-2223）。注释给的理由是：改成 spawn 之后，stdin 不再像 output() 那样默认置 null，继承来的 stdin 可能是终端或管道，交互式 rc 文件里的读操作会永久阻塞。这是一个很容易被忽略的差异——从 output() 换成 spawn() 并不是等价改写。

给一个探测预算。 常量 INSTALL_PROBE_TIMEOUT 定义在 src-tauri/src/commands/misc.rs:2313，取值是 10 秒。上方 :2309-2312 的注释写明了这个预算的语义：到点整组击杀，该条按探测失败降级，预检继续往下走——不是整个动作失败。新增的 run_probe_version_command 非 Windows 版在 :2320、Windows 版在 :2345，都走 wait_child_output(child, CommandDeadline::from_timeout(Some(INSTALL_PROBE_TIMEOUT)))；CommandDeadline 在 :3027，wait_child_output 在 :3094。

需要提醒一句：10 秒是 v3.20.1 源码里的常量，不是设置项，而且会随版本变动。它约束的是升级预检里单条探测的等待上限，不是「你的检查一定十秒内结束」——按 :2309-2312 注释的说法，这条预检要对每个工具开一次登录 shell、对每处安装跑一次 --version，其中任何一条挂死都会卡住整个「全部升级」预检。所以这个预算是发给每一条探测的，不是发给整轮检查的。

顺手把另一条链路划开，免得对号入座：「关于」面板里的版本探测走的不是这条路。AboutSection.tsx:361-365 是用 Promise.all 把受管的那批工具并发探完的，代码注释写明后端原本是串行 await、改并发之后总耗时压成「最慢的那一个」。所以上面那个单条探测预算是升级预检这条链路的事，版本探测那条既不走这个常量，也不是一条接一条地等，两者别混着理解。

Windows 侧要单独看

Windows 上没有控制终端与作业控制那套机制，所以前两件事对 Windows 用户不成立，但第四件成立：旧的 Windows 分支用的是不带超时的 .output()。修复把 Windows 的命令构造抽成 build_windows_tool_command，同样接到带 deadline 的 wait_child_output 上；到点之后由 terminate_child_tree 走 taskkill /T /F 整树击杀。整树这个词很关键——Windows 上探测的往往是一个 .cmd shim，杀掉 shim 进程本身而不杀它拉起来的子进程，等于没杀。

处置之后怎么验证

仓库里留下了可以直接对照的护栏。src-tauri/src/commands/misc.rs:4692 起新增了两个用例：一个覆盖探测 helper 的正常路径，另一个是 :4708 的 isolated_hung_child_is_killed_on_deadline——用一个很短的 deadline（v3.20.1 的用例里写的是 200 毫秒，同样是会随版本变的测试常量）杀掉一个故意挂死的子进程。:4703-4709 的注释把它标成了回归护栏：改回 process_group 就会破。

对使用者来说，可验证的点是版本口径：v3.19.2 时这条预检路径没有超时，一旦踩中就是永久挂起；v3.20.1 已经改为单条探测到点降级、预检继续。所以先确认自己跑的是哪个版本，比反复重试有意义。

什么情况说明不是这个原因

排查文章最容易漏掉的就是这一节，但它才是能省下时间的部分。以下四种看着像挂死，实际不是：

一、显示的是「未安装」而不是一直等。 那大概率是另一条修复处理的问题：de9af49a（#6284）解决的是 Windows 上进程继承的 PATH 与注册表里记着的 PATH 不是同一份——应用内自更新后被拉起的进程只继承机器级 PATH、丢掉用户级 PATH，装在用户 PATH 位置的 CLI 就一律显示未安装。症状是「查不到」，不是「查不完」。

二、所有按钮都点不动。 AboutSection.tsx:757-819 的 handleRunToolAction 是一个统一入口锁，:749-756 的注释列出了它要堵的三个并发窗口，在飞的工具登记在 preflightTools 这个 Set 里，:846-849 汇总成 isAnyBusy 把按钮整体禁用。有别的工具在跑时点不动是设计如此。同理，:577-747 的 executeRun 是逐工具串行的，:584-586 的注释解释了原因：后端把整批拼成单个脚本加 set -e，会在第一个失败处中止整批。串行意味着工具越多总时长越长，这不是卡住。

三、动作确实在执行，只是没有指示。 这条修复里还有纯 UI 的一半：AboutSection.tsx:263-268 引入了 fromBatchEntry 标志，标记本次操作是否来自「全部升级」入口，:761、:783、:806、:823 用它驱动批量按钮的加载态，贯穿预检、确认对话框、执行三个阶段。换句话说，此前那种「像是没响应」有一部分根本不是没执行，而是缺少加载指示。

四、结果回来了但显示的是旧值。 AboutSection.tsx:201 有一个模块级的版本缓存 TTL（v3.20.1 是 10 分钟，同样会随版本变），:227-239 是 stale-while-revalidate 式的初始化：有缓存哪怕已过期也先展示旧值。:195-204 的注释讲了动机——Tabs 切走会卸载非激活面板，每次切回来全量重查等于每个工具一次子进程加一次网络请求。所以「数值没变」可能只是缓存还没过期。

还有一类容易误判的：:643-656 把「退出码 0 但仍然探不到版本」单独归为 notRunnable 这一档软失败，代码注释举的例子是某个 CLI 要求更高的 Node 版本。这种情况命令是跑完了的，不属于挂死。

把这几条排掉之后再回头看前面那四件事，命中率会高很多。

---

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