# 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` | — |

## 冲突警告

当检测到冲突时，界面顶部会显示黄色警告横幅：

```
⚠️ 检测到系统环境变量冲突
发现 X 个环境变量可能会覆盖您的配置
[查看详情] [×]
```

## 查看冲突详情

点击「查看详情」按钮查看详细信息：

| 字段 | 说明 |
|------|------|
| 变量名 | 环境变量名称 |
| 变量值 | 当前设置的值 |
| 来源 | 变量的来源位置 |

### 来源类型

| 来源 | 说明 |
|------|------|
| 用户环境变量 (注册表) | Windows 用户级环境变量 |
| 系统环境变量 (注册表) | Windows 系统级环境变量 |
| 系统环境变量 | macOS/Linux 当前进程环境里的变量 |
| Shell 配置文件 | macOS/Linux 的 shell 配置文件（如 `~/.zshrc`），界面里显示为文件路径 |

## 处理冲突

### 选择要删除的变量

1. 勾选要删除的环境变量
2. 或点击「全选」选择所有冲突变量

### 删除变量

1. 点击「删除选中」按钮
2. 在「确认删除环境变量」对话框里点「确认删除」
3. CC Switch 会自动备份并删除选中的变量；删除后需要重启应用或终端才能生效

### 自动备份

删除前会自动备份：

- 备份位置：`~/.cc-switch/backups/env-backup-<时间戳>.json`
- 备份格式：JSON 文件
- 包含变量名、值、来源等信息
- 可在「设置 → 数据 → 备份与恢复」下方的「其他备份」里查看这类备份（名称为「环境变量清理备份」），也可以在那里清理；清理后无法再查到被删变量的原值

## 忽略警告

如果确认冲突不影响使用，可以：

1. 点击警告横幅右侧的关闭按钮（×）
2. 警告会在本次运行期间隐藏
3. 下次启动时会重新检测

## 手动处理

如果不想通过 CC Switch 删除，可以手动处理：

### Windows

1. 打开「系统属性 → 高级 → 环境变量」
2. 在用户变量或系统变量中找到冲突变量
3. 删除或修改变量

### macOS / Linux

1. 编辑 shell 配置文件（如 `~/.zshrc`、`~/.bashrc`）
2. 删除或注释掉相关的 `export` 语句
3. 重新加载配置：`source ~/.zshrc`

## 为什么会冲突

环境变量的优先级通常高于配置文件，可能导致：

- CC Switch 设置的供应商配置被覆盖
- API 请求发送到错误的端点
- 使用错误的 API 密钥

## 最佳实践

1. **使用 CC Switch 管理配置**：避免在系统环境变量中设置 API 密钥
2. **定期检查**：关注冲突警告，及时处理
3. **备份重要变量**：删除前确认已备份

## 恢复已删除的变量

如果误删了环境变量：

1. 找到备份文件：`~/.cc-switch/backups/` 下的 `env-backup-<时间戳>.json`
2. 打开对应的 JSON 文件
3. 手动恢复变量到系统环境