5.4 环境变量冲突¶
功能说明¶
CC Switch 会自动检测系统环境变量与应用配置的冲突,避免配置被意外覆盖。
检测的环境变量:
| 应用 | 检测范围 | 常见变量 |
|---|---|---|
| Claude Code | 以 ANTHROPIC 开头的变量 |
ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL |
| Codex | 以 OPENAI 开头的变量 |
OPENAI_API_KEY |
| Gemini CLI | 以 GEMINI、GOOGLE_GEMINI 开头的变量 |
GEMINI_API_KEY |
| Grok Build | XAI_API_KEY、GROK_DEFAULT_MODEL |
— |
冲突警告¶
当检测到冲突时,界面顶部会显示黄色警告横幅:
查看冲突详情¶
点击「查看详情」按钮查看详细信息:
| 字段 | 说明 |
|---|---|
| 变量名 | 环境变量名称 |
| 变量值 | 当前设置的值 |
| 来源 | 变量的来源位置 |
来源类型¶
| 来源 | 说明 |
|---|---|
| 用户环境变量 (注册表) | Windows 用户级环境变量 |
| 系统环境变量 (注册表) | Windows 系统级环境变量 |
| 系统环境变量 | macOS/Linux 当前进程环境里的变量 |
| Shell 配置文件 | macOS/Linux 的 shell 配置文件(如 ~/.zshrc),界面里显示为文件路径 |
处理冲突¶
选择要删除的变量¶
- 勾选要删除的环境变量
- 或点击「全选」选择所有冲突变量
删除变量¶
- 点击「删除选中」按钮
- 在「确认删除环境变量」对话框里点「确认删除」
- CC Switch 会自动备份并删除选中的变量;删除后需要重启应用或终端才能生效
自动备份¶
删除前会自动备份:
- 备份位置:
~/.cc-switch/backups/env-backup-<时间戳>.json - 备份格式:JSON 文件
- 包含变量名、值、来源等信息
- 可在「设置 → 数据 → 备份与恢复」下方的「其他备份」里查看这类备份(名称为「环境变量清理备份」),也可以在那里清理;清理后无法再查到被删变量的原值
忽略警告¶
如果确认冲突不影响使用,可以:
- 点击警告横幅右侧的关闭按钮(×)
- 警告会在本次运行期间隐藏
- 下次启动时会重新检测
手动处理¶
如果不想通过 CC Switch 删除,可以手动处理:
Windows¶
- 打开「系统属性 → 高级 → 环境变量」
- 在用户变量或系统变量中找到冲突变量
- 删除或修改变量
macOS / Linux¶
- 编辑 shell 配置文件(如
~/.zshrc、~/.bashrc) - 删除或注释掉相关的
export语句 - 重新加载配置:
source ~/.zshrc
为什么会冲突¶
环境变量的优先级通常高于配置文件,可能导致:
- CC Switch 设置的供应商配置被覆盖
- API 请求发送到错误的端点
- 使用错误的 API 密钥
最佳实践¶
- 使用 CC Switch 管理配置:避免在系统环境变量中设置 API 密钥
- 定期检查:关注冲突警告,及时处理
- 备份重要变量:删除前确认已备份
恢复已删除的变量¶
如果误删了环境变量:
- 找到备份文件:
~/.cc-switch/backups/下的env-backup-<时间戳>.json - 打开对应的 JSON 文件
- 手动恢复变量到系统环境
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cc/cc-switch