CC-Switch是一款轻量化AI编程工具切换管理工具，主打一键切换Claude Code、Gemini CLI、Codex等主流AI命令行工具，解决多AI工具冲突、环境错乱、版本不兼容等问题。本文整理2026年最新官方安装流程，覆盖Windows、macOS、Linux三大系统，包含环境依赖配置、安装包下载、报错解决、初始化设置，新手可直接照着操作。

一、CC-Switch安装前置准备（全平台通用）

CC-Switch正常运行依赖Node.js运行环境，所有系统安装前必须提前部署，否则会出现启动失败、命令失效、工具加载异常等问题。

1. 推荐版本：Node.js 18 LTS 及以上稳定版（不建议使用测试版、最新非LTS版本）

2. 下载地址：Node.js官方官网，优先选择系统对应LTS安装包

3. 环境验证方法（安装Node.js后执行）：

node -v
npm -v

输出版本号即代表环境配置成功，无输出则需要重新安装并配置系统环境变量。

二、CC-Switch官方下载渠道（安全无捆绑）

安装包区分：根据自身电脑系统、芯片架构选择对应安装文件

CC-Switch安装包最新版下载链接：https://pan.quark.cn/s/b75efb9261f0

三、CC-Switch Windows系统详细安装步骤（Win10/Win11通用）

Windows提供MSI正式安装版（推荐）和ZIP便携版两种安装方式，分别适配长期使用和临时使用场景。

方式1：MSI安装版（新手首选，支持自动更新、环境自动配置）

1. 进入GitHub Releases页面，下载最新版 CC-Switch.msi 安装包

2. 双击启动安装程序，若弹出Windows Defender SmartScreen安全拦截，点击【更多信息】-【仍要运行】，属于系统正常拦截，安装包无风险

3. 自定义安装路径，禁止安装在含中文、空格、特殊字符的文件夹，建议默认路径或纯英文路径

4. 关键勾选配置：务必勾选【添加桌面快捷方式】【自动添加系统PATH环境变量】，避免后续命令无法全局调用

5. 点击【立即安装】，等待进度条完成，勾选【立即启动CC-Switch】，点击完成即可结束安装
   

方式2：ZIP便携版（免安装、无残留、适合临时使用）

1. 下载对应系统的 CC-Switch-Portable.zip 压缩包

2. 解压至非系统盘固定目录（推荐D盘工具文件夹，不要放在桌面、下载文件夹，避免清理缓存误删文件）

3. 打开解压文件夹，双击主程序即可启动，无需安装，解压即用

4. 手动配置：如需全局调用命令，手动将程序目录添加到系统环境变量PATH中

四、macOS系统CC-Switch详细安装步骤（Intel/M芯片通用）

macOS支持Homebrew一键安装（推荐）和DMG镜像手动安装，适配Intel芯片和Apple M系列芯片。

方式1：Homebrew命令安装（最简方式，自动适配芯片）

打开终端，依次执行以下两行命令，全程自动安装、配置环境，无需手动干预：

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

安装完成后，终端输入 cc-switch 即可直接启动。

方式2：DMG手动安装（适合无Homebrew环境）

1. 对应芯片下载安装包：M系列芯片选择 CC-Switch_arm64.dmg，Intel芯片选择 CC-Switch_x64.dmg

2. 双击打开DMG文件，将CC-Switch程序拖入应用程序文件夹

3. 首次打开提示“无法验证开发者”时，前往【系统设置】-【隐私与安全性】，允许程序运行即可
   

五、Linux系统CC-Switch详细安装步骤（全发行版适配）

适配Debian、Ubuntu、Fedora、Arch、CentOS等主流Linux发行版，提供多格式安装包。

1. Debian/Ubuntu系统（.deb格式）

sudo apt update
sudo dpkg -i cc-switch_amd64.deb
sudo apt install -f

2. Fedora/RHEL系统（.rpm格式）

sudo dnf install ./cc-switch-*.rpm

3. 通用免装版（.AppImage格式，全发行版通用）

1. 下载CC-Switch.AppImage文件

2. 终端添加执行权限：chmod +x CC-Switch.AppImage

3. 直接运行：./CC-Switch.AppImage

4. Arch系统卸载/更新命令

paru -R cc-switch-bin

六、安装完成验证方法（全平台通用）

1. 打开系统终端/CMD/PowerShell

2. 输入验证命令：

cc-switch -v

3. 输出版本号（v3.16.1）即代表安装成功、环境配置正常；提示“不是内部命令”则为环境变量配置失败，重新勾选/手动配置PATH即可。

七、常见安装报错及解决方法

问题1：启动提示Node.js环境缺失

解决：重新安装Node.js 18及以上LTS版本，安装后重启电脑，刷新系统环境变量。

问题2：Windows安装后无法全局调用命令

解决：安装时未勾选环境变量配置，手动将CC-Switch安装目录添加到系统PATH，重启终端即可。

问题3：macOS提示程序被拦截、无法打开

解决：隐私与安全性中放行程序，或执行终端绕过命令：xattr -d com.apple.quarantine 程序路径

问题4：Linux安装依赖报错

解决：执行 sudo apt install -f 自动修复依赖缺失，重新安装即可。

八、新手初始化简单设置

1. 首次打开软件后，自动扫描本地已安装的Claude Code、Gemini CLI等AI工具

2. 在工具列表中勾选需要托管的AI程序，开启一键切换功能

3. 开启后台常驻、自动更新，后续无需重复配置，直接使用即可