# CC Switch v3.11.1

> 回退部分键值合并、恢复通用配置片段与多项修复

**[English →](v3.11.1-en.md) | [日本語版 →](v3.11.1-ja.md)**

---

## 概览

CC Switch v3.11.1 是一个修复版本，回退了 v3.11.0 中引入的**部分键值合并**架构，恢复经过验证的「**全量配置覆写 + 通用配置片段**」机制，同时修复了多个 UI 和平台兼容性问题。

**发布日期**：2026-02-28

**更新规模**：8 commits | 52 files changed | +3,948 / -1,411 lines

---

## 重点内容

- **恢复全量配置覆写 + 通用配置片段**：因关键数据丢失问题回退部分键值合并，恢复完整配置快照写入和通用配置片段 UI
- **代理面板交互优化**：代理开关移入面板内部，接管选项一目了然
- **主题与紧凑模式修复**：「跟随系统」主题现可正确自动更新，紧凑模式退出恢复正常
- **Windows 兼容性**：禁用环境检查和一键安装，防止协议处理程序副作用

---

## 回退

### 恢复全量配置覆写 + 通用配置片段

回退了 v3.11.0 中引入的部分键值合并重构（revert 992dda5c）。

**回退原因**：部分键值合并方案存在三个关键缺陷：
1. **切换时数据丢失**：非白名单的自定义字段在供应商切换时被静默丢弃
2. **回填永久剥离**：回填操作永久移除数据库中的非键字段，造成不可逆的数据丢失
3. **维护成本高**：「键字段」白名单需要随新配置项不断维护，容易遗漏

**恢复的内容**：
- 供应商切换时的完整配置快照写入（可预测的全量覆写）
- 通用配置片段 UI 及后端命令
- 6 个前端文件（3 个组件 + 3 个 hooks）

**迁移说明**：
- 如果你在 v3.11.0 中切换供应商后丢失了自定义字段，请重新导入配置或手动补回缺失的字段
- 通用配置片段功能已恢复——用它来定义切换供应商时需要保留的共享配置

---

## 变更

- **代理面板交互优化**：将代理开关从折叠面板标题移入面板内部，紧邻应用接管选项。确保用户启用代理后能立即看到接管配置，避免「只开代理不接管」的常见误操作
- **OpenCode/OpenClaw 手动导入**：移除启动时自动导入供应商配置的行为，改为在空状态页显示「导入当前配置」按钮，与 Claude/Codex/Gemini 保持一致

---

## 修复

- **「跟随系统」主题不自动更新**：改用 Tauri 原生主题追踪（`set_window_theme(None)`），使 WebView 的 `prefers-color-scheme` 媒体查询能正确响应 OS 主题切换
- **紧凑模式无法退出**：恢复 `toolbarRef` 上的 `flex-1` class，修复 `useAutoCompact` 的退出条件因宽度计算错误而永远不触发的问题
- **代理接管 Toast 显示 {{app}}**：为 proxy takeover 的 i18next `t()` 调用补充缺失的 `app` 插值参数
- **Windows 协议处理副作用**：在 Windows 上禁用环境检查和一键安装功能，防止协议处理程序注册引发的意外副作用

---

## 说明与注意事项

- **通用配置片段已恢复**：如果你在 v3.10.x 及更早版本中使用了此功能，它的工作方式与之前完全一致。用它来定义切换供应商时需要保留的共享配置。
- **v3.11.0 部分键值合并用户**：如果你在 v3.11.0 中切换供应商后发现配置字段丢失，请重新导入配置以恢复。

---

## 下载与安装

访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。

### 系统要求

| 系统    | 最低版本                      | 架构                                |
| ------- | ----------------------------- | ----------------------------------- |
| Windows | Windows 10 及以上             | x64                                 |
| macOS   | macOS 10.15 (Catalina) 及以上 | Intel (x64) / Apple Silicon (arm64) |
| Linux   | 见下表                        | x64                                 |

### Windows

| 文件                                     | 说明                                |
| ---------------------------------------- | ----------------------------------- |
| `CC-Switch-v3.11.1-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.11.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |

### macOS

| 文件                             | 说明                                                      |
| -------------------------------- | --------------------------------------------------------- |
| `CC-Switch-v3.11.1-macOS.zip`    | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
| `CC-Switch-v3.11.1-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                              |

> **注意**：由于作者没有苹果开发者账号，首次打开可能出现「未知开发者」警告，请先关闭，然后前往「系统设置」→「隐私与安全性」→ 点击「仍要打开」，之后便可以正常打开

### Homebrew（macOS）

```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

更新：

```bash
brew upgrade --cask cc-switch
```

### Linux

| 发行版                                  | 推荐格式    | 安装方式                                                               |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |