cc-switch 跨平台安装实战指南：系统要求、三平台安装流程与自动更新机制解析

本篇基于 cc-switch 仓库官方用户手册的安装指南（docs/user-manual/en/1-getting-started/1.2-installation.md），完整覆盖 Windows、macOS、Linux 三大平台的安装与卸载流程，并结合仓库源码（打包配置、更新器、Rust 后端）解析自动更新机制与配置目录的底层实现，帮助读者在任一平台上正确安装、验证并安全卸载 cc-switch，同时理解各安装选项背后的工程细节。

一、官方渠道与系统要求

安装 cc-switch 前必须先确认下载渠道。官方渠道仅有三个：官方网站 ccswitch.io、GitHub Releases 发布页，以及项目源代码仓库。任何要求付费、充值或索要登录凭据的 "CC Switch" 站点或客户端均非官方。

各平台最低系统要求如下（与原文档一致）：

系统	最低版本	架构
Windows	Windows 10 或更高	x64
macOS	macOS 12 (Monterey) 或更高	Intel (x64) / Apple Silicon (arm64)
Linux	见下文各发行版说明	x64 / ARM64

仓库源码可以佐证这些约束：

• macOS 最低版本由 Tauri 打包配置硬性声明为 12.0，见 tauri.conf.json 中的 bundle.macOS.minimumSystemVersion: "12.0"；
• 当前仓库版本为 3.20.0（package.json 与 tauri.conf.json 的 version 字段一致），应用标识符为 com.ccswitch.desktop，即 Linux 各安装包（deb/Flatpak/桌面文件）统一使用的 App ID；
• 前端基于 React 18 + Vite，桌面壳为 Tauri 2（@tauri-apps/cli ^2.8.0，package.json），Rust 后端工具链固定为 1.95（rust-toolchain.toml）。

二、前置准备

2.1 安装 Node.js

CC Switch 所管理的 CLI 工具（Claude Code、Codex、Gemini CLI）依赖 Node.js 运行环境，推荐版本为 Node.js 18 LTS 及以上。

Windows：

1. 前往 Node.js 官网（nodejs.org）；
2. 下载 LTS 版本安装包；
3. 运行安装程序并按提示完成；
4. 验证安装：

node --version
npm --version

macOS：

# 使用 Homebrew 安装
brew install node

# 或使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Linux：

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 或使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

2.2 安装 CLI 工具

三个受管 CLI 工具均提供 Homebrew 与 npm 两种安装方式：

Claude Code

# 方式一：Homebrew（macOS 推荐）
brew install claude-code

# 方式二：npm
npm install -g @anthropic-ai/claude-code

Codex

# 方式一：Homebrew（macOS 推荐）
brew install codex

# 方式二：npm
npm install -g @openai/codex

Gemini CLI

# 方式一：Homebrew（macOS 推荐）
brew install gemini-cli

# 方式二：npm
npm install -g @google/gemini-cli

这些工具安装完成后，cc-switch 才能在其各自的用户级配置目录（如 ~/.claude.json、~/.codex、~/.gemini，参见 Flatpak 清单 flatpak/com.ccswitch.desktop.yml 中的权限注释）中生成与切换供应商配置。

三、按平台安装 CC Switch

3.1 Windows

方式一：MSI 安装包

1. 前往 GitHub Releases 发布页；
2. 下载 CC-Switch-v{version}-Windows.msi；
3. 双击运行安装程序；
4. 按提示完成安装。

方式二：便携版（无需安装）

1. 下载 CC-Switch-v{version}-Windows-Portable.zip；
2. 解压到任意目录；
3. 运行 CC-Switch.exe。

从打包配置看，Windows 安装包使用 WiX 模板 wix/per-user-main.wxs，有两个值得注意的工程细节：

• 按用户（per-user）安装：模板声明 InstallScope="perUser" 与 InstallPrivileges="limited"（第 28-29 行），默认安装到当前用户的 LocalAppData\Programs\CC Switch 目录，无需管理员权限；
• 注册深链接协议：安装过程会在 HKCU\Software\Classes\ccswitch 下注册 ccswitch:// URL 协议（模板第 141-152 行的 deep link 段落），用于配置深链接导入功能，该协议在 Tauri 侧由 tauri.conf.json 的 plugins.deep-link.desktop.schemes: ["ccswitch"] 声明。

3.2 macOS

方式一：Homebrew（推荐）

# 安装
brew install --cask cc-switch

# 升级到最新版本
brew upgrade --cask cc-switch

方式二：手动下载

1. 下载 CC-Switch-v{version}-macOS.dmg（推荐）或 CC-Switch-v{version}-macOS.zip；
2. 打开 DMG，或解压 zip 得到 CC Switch.app；
3. 将其拖入 Applications（应用程序）文件夹。

签名与公证：macOS 版已通过 Apple 签名与公证（signed & notarized），下载安装后可直接打开，无需在"系统设置"中额外放行或右键解锁。

macOS 构建的 Info.plist（src-tauri/Info.plist）注册了 ccswitch:// 自定义 URL 协议（CFBundleURLSchemes），即 App 安装后同样具备深链接导入能力。

3.3 Linux

Arch Linux（AUR）

使用 AUR helper 安装：

# 使用 paru
paru -S cc-switch-bin

# 或使用 yay
yay -S cc-switch-bin

Debian / Ubuntu（deb 包）

1. 按架构下载 CC-Switch-v{version}-Linux-x86_64.deb 或 CC-Switch-v{version}-Linux-arm64.deb；
2. 安装：

sudo dpkg -i CC-Switch-v{version}-Linux-*.deb

# 如出现依赖问题
sudo apt-get install -f

AppImage（通用方案）

1. 按架构下载 CC-Switch-v{version}-Linux-x86_64.AppImage 或 CC-Switch-v{version}-Linux-arm64.AppImage；
2. 添加可执行权限：

chmod +x CC-Switch-v{version}-Linux-*.AppImage

3. 运行：

./CC-Switch-v{version}-Linux-*.AppImage

补充：Flatpak 清单。仓库内附带 flatpak/com.ccswitch.desktop.yml Flatpak 清单，基于 GNOME 46 运行时构建。清单中可以看到它为托盘图标申请了 org.kde.StatusNotifierWatcher 与 xdg-run/tray-icon 权限（托盘图标依赖），并默认授予完整 Home 访问权限，以便读写 ~/.cc-switch、~/.claude、~/.codex、~/.gemini 及各 CLI 配置目录。该清单面向 "下载后手动运行" 场景，若发布到 Flathub 需收紧权限（详见 flatpak/README.md）。

四、安装验证

安装完成后启动 CC Switch，确认以下三点：

1. 应用窗口正常显示（默认窗口 1000×650，最小 900×600，见 tauri.conf.json 的 app.windows 配置）；
2. 系统托盘出现 CC Switch 图标；
3. 顶部的应用切换器（App Switcher）显示已启用的受管应用，并能切换到目标应用的面板。

这三项检查分别对应主窗口、托盘模块（src-tauri/src/tray.rs）与应用切换组件（src/components/AppSwitcher.tsx），可视为安装完整性最直观的验收标准。

五、自动更新机制解析

官方文档说明：CC Switch 内置自动更新——启动时自动检查更新、发现新版本时在 UI 中提示、点击即可下载安装；也可在"设置 > 关于"中手动检查。仓库源码印证了这条完整链路：

后端更新器配置。tauri.conf.json 的 plugins.updater 声明了两个检查端点（按顺序回退）：

• https://dl.ccswitch.io/latest.json（官方 CDN）
• GitHub Releases 的 latest/download/latest.json（兜底）

同时内置了 pubkey（minisign 公钥）用于校验更新包签名，createUpdaterArtifacts: true（第 39 行）表示构建时生成更新器所需的签名产物。

前端检查逻辑。src/lib/updater.ts 封装了 checkForUpdate：动态导入 @tauri-apps/plugin-updater 的 check 方法（默认 30 秒超时），并将结果归一化为 up-to-date / available 两种状态。src/contexts/UpdateContext.tsx 在应用启动时延迟约 1 秒触发自动检查（避免影响启动体验），并支持"忽略此版本"——被忽略的版本号存入 localStorage（键 ccswitch:update:dismissedVersion，含旧键 dismissedUpdateVersion 的迁移逻辑，见第 31-32 行），同一版本不再重复提醒。

Windows MSI 的升级能力。per-user 模板配置了 REINSTALLMODE=amus（全量重装文件、重写注册表、重建快捷方式）并允许 AllowSameVersionUpgrades（wix/per-user-main.wxs），这意味着内置更新器覆盖安装同一版本也不会残留旧文件。

六、配置目录与数据位置

卸载章节提及的 ~/.cc-switch/ 目录是 cc-switch 的核心数据位置。Rust 侧实现见 src-tauri/src/config.rs：

• get_app_config_dir() 默认返回 ~/.cc-switch，且支持通过设置中的目录覆盖项（get_app_config_dir_override()）指向自定义位置；
• 目录内包含主配置 config.json 与 SQLite 数据库 cc-switch.db；
• Windows 上存在一段兼容逻辑：若默认位置没有数据库，但旧版 v3.10.3 曾把库建在 $HOME/.cc-switch（HOME 与真实用户目录不一致的环境），则会回退使用旧位置，避免出现"供应商消失"的错觉（第 210-233 行）。

需要留意：删除 ~/.cc-switch/ 会同时删除本地保存的供应商配置与数据库，仅应在彻底弃用该工具时执行。

七、卸载

Windows

• 通过"设置 > 应用"卸载；
• 或运行安装目录中的卸载程序（WiX 模板在安装目录内生成 Uninstall 快捷方式，指向 msiexec.exe /x [ProductCode]，见 wix/per-user-main.wxs）。

macOS

• 将 CC Switch.app 移入废纸篓；
• 可选：删除配置目录 ~/.cc-switch/。

Linux

# Debian/Ubuntu
sudo apt remove cc-switch

# ArchLinux
paru -R cc-switch-bin

八、小结

cc-switch 的安装路径在三大平台各有推荐方式：Windows 用 per-user MSI（免管理员权限）或便携 zip，macOS 用 Homebrew cask 或签名公证后的 DMG，Linux 用 AUR、deb 或 AppImage。安装与升级均由 Tauri updater 插件 + 双端点 latest.json + minisign 签名校验支撑，数据统一落在 ~/.cc-switch/。按照本文验证清单完成安装后，即可进入后续章节的应用面板与供应商管理。