切了供应商还是走老地址：CC Switch 的环境变量冲突检查在查什么

2026-08-10

在配置管理类工具上最容易踩的一类坑是：你在工具里改了配置，工具也确实把配置文件写对了，但真正跑起来的 CLI 还是走老地址。原因往往不在配置文件，而在优先级更高的环境变量——很多 CLI 会优先读 ANTHROPIC_BASE_URL、OPENAI_API_KEY 这类变量，配置文件反而排在后面。

cc-switch 仓库里为这件事准备了一个专门的检查模块。这篇就只讲这一件事：它到底在查什么、在哪儿查、查到之后能做什么、以及哪些情况它根本查不出来。所有结论都落在 src-tauri/src/services/env_checker.rs 与 env_manager.rs 两个文件的具体行上，你可以自己去仓库里对照。我们读到的是 HEAD c39c903（2026-08-10 采集，仓库内版本号 3.19.2）。

一、关键词表：不是一张固定的变量名清单

第一个反直觉的地方就在这儿。很多人以为这类检查是拿一张写死的变量名清单去比对，但代码里不是。get_keywords_for_app(app) 按应用返回的是一组带匹配语义的关键词，不是变量名列表（src-tauri/src/services/env_checker.rs:39-54）：

app 取值	关键词	匹配语义
`claude`	`ANTHROPIC`	前缀
`codex`	`OPENAI`	前缀
`gemini`	`GEMINI`、`GOOGLE_GEMINI`	前缀
`grokbuild` / `grok`	`XAI_API_KEY`、`GROK_DEFAULT_MODEL`	精确
其余	—（空）	—

两种语义由枚举 EnvKeyword::{Exact, Prefix} 表达，匹配时先把变量名统一转成大写再比（env_checker.rs:33-63）。

这张表值得逐行读三遍，因为它决定了三件事：

第一，Claude / Codex / Gemini 三家是前缀匹配。 这意味着命中的不只是那几个”著名”变量。凡是以 ANTHROPIC 开头的环境变量，在 claude 这一档下都会被算作冲突项列出来——不管它是不是密钥，也不管它是不是你有意设置的。

第二，Grok 那两项是精确匹配。 XAI_API_KEY 与 GROK_DEFAULT_MODEL 必须一字不差才命中。换句话说，同一份代码里对不同应用用了不同宽度的判定口径，这一点在读检查结果时必须心里有数。

第三，_ => vec![]。 不在上述分支里的 app 直接返回空关键词集，也就是走这条路径时永远查不出冲突。这不是”没有冲突”，是”没有检查项”，两者结论完全不同。

二、单测把边界钉死了：前缀只在开头算

如果你担心”前缀匹配”会不会把一堆不相干的变量都算进来，仓库里有现成的答案——文件末尾的单元测试直接断言了边界（env_checker.rs:193-217）：

MY_ANTHROPIC_API_KEY 不算冲突；NOT_ANTHROPIC 不算冲突。前缀判定用的是”以此开头”，而不是”包含”。
Grok 侧同理且更严：XAI_API_KEY_BACKUP 不算，GROK_HOME 不算——因为它们走的是精确匹配。

这是本篇最值得记住的一处。你把变量改名叫 ANTHROPIC_BASE_URL_OLD 留着备用，它仍然会被列为冲突（以 ANTHROPIC 开头）；而你把 Grok 的 key 改名叫 XAI_API_KEY_BACKUP 留着备用，它不会被列出来。同一个”留个备份”的习惯，在两家的判定下结果相反。

核对动作很简单：打开 env_checker.rs，先看 39-63 行的关键词表与匹配函数，再看 193-217 行的断言。这两段加起来不到六十行，读完就不会再猜。

三、Windows 与非 Windows，扫的位置不一样

第二处容易翻车的地方是平台差异。这个模块的 check_system_env 有两份实现，靠 cfg(target_os = "windows") 分开：

平台	扫描位置	出处
Windows	`HKEY_CURRENT_USER\Environment`、`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment` 两处注册表	`env_checker.rs:66-100`
非 Windows	当前进程环境变量，外加 7 个 shell 配置文件	`env_checker.rs:102-170`

非 Windows 那 7 个文件是：~/.bashrc、~/.bash_profile、~/.zshrc、~/.zprofile、~/.profile、/etc/profile、/etc/bashrc。命中时 source_path 会记成 文件:行号 的形式，也就是说结果里能直接告诉你是哪个文件的第几行写的（env_checker.rs:102-170）。

对照着看就能发现：两侧扫的东西不是一回事。非 Windows 侧既看当前进程环境、又把 shell 启动脚本翻了一遍；Windows 侧读的是注册表里的用户级与机器级持久化环境变量。所以在 Windows 上，如果冲突来源不在这两个注册表键里，这个检查就不会把它列出来——它给出的是”这两处注册表里有什么”，不是”你那个终端里最终生效的是什么”。这一点决定了下面的排查顺序。

四、删之前必先备份：目录、文件名与失败时的行为

检查出来之后，仓库里配套的是三个 Tauri 命令（src-tauri/src/commands/env.rs:6-22）：

命令	作用
`check_env_conflicts`	按 app 查冲突，返回冲突列表
`delete_env_vars`	删除传入的冲突项
`restore_env_backup`	从备份文件恢复

delete_env_vars 的第一步是强制备份，不是可选项：备份目录是 ~/.cc-switch/backups，文件名是 env-backup-{YYYYMMDD_HHMMSS}.json，时间戳取的是 UTC 时间（src-tauri/src/services/env_manager.rs:44-71）。UTC 这点在排文件顺序时要留神——文件名上的时刻和你本地时钟不是一个东西。

还有一处设计值得单独说：删除中途失败时，备份不会被清掉，错误信息里会把备份路径一起带出来（env_manager.rs:26-38）。也就是说，如果一批冲突项删到一半出错，你手里仍然有一份完整的删除前快照，路径就在报错文本里，配合 restore_env_backup 可以走回去。

顺带说清楚边界：这里删的是你本机真实的环境变量（Windows 侧落在注册表，类 Unix 侧涉及 shell 配置），备份文件里按结构存的是变量名、值与来源。备份文件本身就可能包含密钥明文，它躺在你的用户目录里——请按处理密钥的方式对待它，不要随手拷到共享盘或贴进 issue。这类做法属于通用运维常识，不是该项目文档里的规定。

五、文档与代码对不上的两处

仓库的用户手册里有一节 docs/user-manual/zh/5-faq/5.4-env-conflict.md 专门讲这个功能。我们把它和代码逐条比了一遍，有两处口径对不上，照实记下来：

其一，备份目录。 手册写的是 ~/.cc-switch/env-backups/（5.4-env-conflict.md:60）；代码里 get_backup_dir() 拼出来的是 ~/.cc-switch/backups，文件名 env-backup-{时间戳}.json（env_manager.rs:50、:69-71）。两处不一致；以我们实读的仓库状态为准，你要去翻备份文件时按代码那个路径找。

其二，检测范围。 手册那一节列出的具体变量名只有四个：ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、OPENAI_API_KEY、GEMINI_API_KEY（5.4-env-conflict.md:7-11）；代码是按前缀匹配 ANTHROPIC* / OPENAI* / GEMINI* / GOOGLE_GEMINI*，另加 Grok 的两个精确项 XAI_API_KEY 与 GROK_DEFAULT_MODEL（env_checker.rs:39-63），手册未提 Grok 这两项。两处不一致，说到这里为止。

差异本身不影响你用，但会影响你读结果时的预期：按手册的四个变量名去预判，实际列出来的条目可能比你想的多（前缀命中）；反过来，如果你在找 Grok 相关的变量，预期又可能比实际的多（那两项之外都不查）。

六、一条可执行的排查路径

把上面几节串成实际能走的流程：

现象。 在工具里切换了供应商，某个 CLI 的实际请求仍然指向老地址或老密钥。

怎么确认是这个原因。 按你用的那个 CLI 选对 app 档位跑 check_env_conflicts，看返回的冲突列表。列表里每条都带 source_type 与 source_path：非 Windows 上是 文件:行号，你可以直接打开那一行确认；Windows 上是那两个注册表路径之一。如果你想绕开工具自己核，在 Windows 上可以用系统自带的 reg query 去看那两个键，在类 Unix 上直接 env 加上把那 7 个文件翻一遍——这两条是通用的系统命令，不是该项目文档里给的步骤。

处置。 代码给出的路径是 delete_env_vars：先备份到 ~/.cc-switch/backups，再逐条删除；出错则保留备份并把路径带在错误信息里。想撤回就用 restore_env_backup 指向那个备份文件。

处置后怎么验证。 再跑一次 check_env_conflicts，看那几条是否已经不在列表里。要注意的是，环境变量的生效通常需要重开终端或重新登录会话——旧终端里的进程仍然持有它启动时那份环境副本，这属于操作系统的通用行为，与本项目无关。

什么情况说明不是这个原因。 这一步别省，它决定你要不要继续往这个方向挖：

冲突列表返回空，且你用的 app 确实在第一节那张表的分支里（claude / codex / gemini / grokbuild）。如果你用的是表外的应用，返回空只说明这条路径没有检查项，不代表没有环境变量在干扰。
你在 Windows 上，而那个变量是在当前终端会话里临时设的——它不在那两个注册表键中，这个检查按其实现范围就不会列出它。
变量名不符合匹配规则：比如 Grok 侧的 XAI_API_KEY_BACKUP（精确匹配不中），或者非 ANTHROPIC 开头的自定义变量（前缀匹配不中）。这类情况检查返回空是符合代码语义的，问题得往别处找。
冲突项已经删干净、终端也重开过，行为仍然没变。那就说明配置来源不在环境变量这一层，应该转去核对该 CLI 自身的配置文件与工具写入的目标文件是否是同一份。

七、几句必要的提醒

这个模块碰的是你本机的真实环境变量与 shell 启动脚本，删除是有实际后果的操作：如果某个 ANTHROPIC_* 变量是你别的脚本或 CI 本地调试在用的，它同样会出现在冲突列表里。列表里列出的是”按关键词命中的变量”，不是”应该删的变量”——判断哪些该删只能由你自己做。

另外，密钥类环境变量与备份文件都属于本机敏感数据。仓库把强制备份、失败保留备份、错误信息带路径这几件事都做进了流程里，这是可核对的代码行为；但它不构成”删了就安全”或”备份了就不会丢”的任何保证，怎么保管这些文件仍然取决于你自己的机器环境。

顺带一提，i18n 里 env 这一节共 21 个叶子键（Python 递归数 src/i18n/locales/en.json），四份语言文件里 en / zh / ja 的键集合完全一致。想知道这个功能对外一共表达了哪些状态与提示语，读那 21 个键比读别的都快。

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