cc-switch/docs/release-note-v3.11.1-zh.md

CC Switch v3.11.1

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

English → | 日本語版 →

---

概览

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 下载对应版本。

系统要求

系统	最低版本	架构
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）

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

更新：

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