奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

三个平台怎么装：msi / dmg / AppImage 与 brew、paru 的取舍

2026-08-10

装一个桌面应用本来不该值得写一篇。但 CC Switch 这个项目的安装环节有一处很容易把人绊住：README 给的三个 Linux 包名，与 CI 脚本拼出来、Release 说明模板里写的名字对不上。

不是包不存在，是名字不一样。README 写的是 CC-Switch-v{版本号}-Linux.AppImage，而 CI 脚本实际拼出来的名字中间多一段架构：CC-Switch-${VERSION}-Linux-${ARCH}.AppImage。用户手册那一层反而和 CI 是一致的。这篇就把三个平台的安装口径逐条摆开，把这处差异标到具体行号，顺便给出一条按你自己的处境倒推的选择路径。

以下全部基于我们本地 clone 的 cc-switch 仓库快照 c39c903（提交日期 2026-08-10），仓库内版本号 3.19.2（package.json、src-tauri/Cargo.toml、src-tauri/tauri.conf.json 三处一致）。我们只读源码与文档文本，没有安装也没有运行过这个桌面应用。

先看系统要求：README 一层，用户手册一层

README 的系统要求写得很简：Windows 10 及以上（README_ZH.md:353）、macOS 12 (Monterey) 及以上（README_ZH.md:354）、Linux 是 Ubuntu 22.04+ / Debian 11+ / Fedora 34+ 等主流发行版（README_ZH.md:355）。

用户手册 1.2 给的是一张带架构的表（docs/user-manual/zh/1-getting-started/1.2-installation.md:7-11）：Windows 10+ 只标了 x64；macOS 12+ 同时支持 Intel (x64) 与 Apple Silicon (arm64)；Linux 标 x64 / ARM64。手册 1.1 的平台清单与 README 一致，另补了「（x64 / ARM64）」（1.1-introduction.md:53-55）。

macOS 那个最低版本在代码里也能对上：Tauri bundle 配置的 minimumSystemVersion 是 "12.0"（src-tauri/tauri.conf.json:52-54）。这是三层口径里少数完全一致的一处。

Windows：msi、Portable zip，以及 README 没提的那个包

README 的 Windows 段只给两个产物：CC-Switch-v{版本号}-Windows.msi 和 CC-Switch-v{版本号}-Windows-Portable.zip（README_ZH.md:359）。安装器用的是 WiX 模板 wix/per-user-main.wxs（src-tauri/tauri.conf.json:47-51）。

用户手册 1.2 记了一个 Windows 侧的处置：msi 双击没有反应时，可以在文件属性 → 常规 → 安全里勾选「解除锁定」（1.2-installation.md:128）。手册把这个动作写进了安装章节，成因属 Windows 通用行为，仓库文档未展开。

README 没写的是 arm64。 CI 另会产出 CC-Switch-$VERSION-Windows-arm64.msi 与 -arm64-Portable.zip（.github/workflows/release.yml:451、497、616）。手册 1.2 那张表里 Windows 一栏也只写了 x64。所以如果你手上是 Windows on ARM 的机器，README 与手册两处都不会告诉你有这个包，你得直接去 Releases 页面按文件名找。

卸载走系统「设置 → 应用」，这是手册给的路径（1.2-installation.md:220-240）。

macOS：brew cask 与 dmg，README 两处都写了「推荐」

macOS 段 README 给了两条路，有意思的是两条路上都出现了「推荐」字样，但推荐的层级不同。

方式一是 Homebrew，README 在这条整体标了「推荐」：

brew install --cask cc-switch
# 更新
brew upgrade --cask cc-switch

（分别见 README_ZH.md:366 与 README_ZH.md:372。）

方式二是手动下载 CC-Switch-v{版本号}-macOS.dmg 或 .zip，而这条路里 README 又在 .dmg 后面标了「推荐」（README_ZH.md:377）。换句话说，「推荐 brew」和「两个手动包里推荐 dmg」是两句话，不是一句。README 同时声明 macOS 版本「已通过 Apple 代码签名和公证，可直接安装打开」（README_ZH.md:379，FAQ 第 4 条同义，README_ZH.md:279-281）。这三个渠道是否真实可用属于仓库之外的事实，我们这次没有联网，没有核实过 Homebrew 里是否真有 cc-switch 这个 cask。

CI 那边还多产一个 README 没提的东西：CC-Switch-${VERSION}-macOS.tar.gz，用途标注是 updater 制品（.github/workflows/release.yml:304）。这个包不是给你手动装的，你在 Releases 里看到它别当成第三种安装方式。

卸载按手册是移入废纸篓，并可选删除 ~/.cc-switch/（1.2-installation.md:220-240）——注意这是可选的，你的供应商配置、密钥、备份都在那个目录里，~/.cc-switch/ 里具体有什么另有一篇专门在讲。

Linux：三个包、两个 AUR 助手，以及那个对不上的文件名

README 的 Linux 段给三种包（README_ZH.md:393-395）：

README 写的文件名适用CI 实际产出的名字
CC-Switch-v{版本号}-Linux.debDebian / UbuntuCC-Switch-${VERSION}-Linux-${ARCH}.deb
CC-Switch-v{版本号}-Linux.rpmFedora / RHEL / openSUSECC-Switch-${VERSION}-Linux-${ARCH}.rpm
CC-Switch-v{版本号}-Linux.AppImage通用CC-Switch-${VERSION}-Linux-${ARCH}.AppImage

右列三个名字分别来自 .github/workflows/release.yml:518、528、536；Release 说明模板里写的也是 -Linux-x86_64 与 -Linux-arm64 两套（.github/workflows/release.yml:617-618）。用户手册 1.2 与 CI 一致，写的是 CC-Switch-v{版本号}-Linux-x86_64.deb / -arm64.deb（1.2-installation.md:177、189）。

所以这里是三处口径：README 无架构后缀，用户手册和 CI 都有。这三处的位置我们都标了行号，你可以自己去核；至于哪一处「才算数」、为什么没同步，本文不做推断。实际操作上你只要记住一件事：按 CI 与 Release 说明模板的写法，中间会多一段架构，比对文件名时把这一段补上。

Arch 系走 AUR。README 标「推荐」的是 paru：

paru -S cc-switch-bin

（README_ZH.md:386。）用户手册另给了 yay 的等价写法 yay -S cc-switch-bin（1.2-installation.md:169-172）。两个都是 AUR 助手，包名同为 cc-switch-bin。卸载对应 sudo apt remove cc-switch 与 paru -R cc-switch-bin（1.2-installation.md:220-240）。

还有一件 Linux 用户容易踩的事：AppImage 这条路上，应用启动时会在 #[cfg(target_os = "linux")] 分支里动环境变量，在较新的 Wayland 加 NVIDIA 组合下可能出现点不动或缩放黑屏，项目为此留了 CC_SWITCH_GDK_BACKEND 这个逃生开关（README_ZH.md:315-321，实现见 src-tauri/src/main.rs:27-31）。这一处我们另有一篇专门讲，这里只提醒你：选 AppImage 之前先知道有这么个开关。

Flatpak：官方 Release 里没有，得自己从 deb 转

README 在 Linux 段末尾明写「官方 Release 不包含 Flatpak 包」，要用得自己从 .deb 构建（README_ZH.md:397，英文版同义 README.md:394）。

仓库里确实备了这套东西。flatpak/ 目录有 4 个文件：README.md、com.ccswitch.desktop.desktop、com.ccswitch.desktop.metainfo.xml、com.ccswitch.desktop.yml。manifest id 是 com.ccswitch.desktop，用途就是把已生成的 .deb 转成 .flatpak（flatpak/README.md:3）。依赖是 flatpak、flatpak-builder 和一个 Flathub remote（用来装 org.gnome.Platform//46 运行时，flatpak/README.md:7-9）。本地构建三步：pnpm tauri build -- --bundles deb → 把 deb 复制成 flatpak/cc-switch.deb → flatpak-builder 加 flatpak build-bundle 导出 CC-Switch-Linux.flatpak（flatpak/README.md:24、30、36-37）。

这份文档里有一段值得单独看：当前 manifest 默认用 --filesystem=home，图的是「下载即用」的便利，文中同时给出了一份可替换的最小权限清单——~/.cc-switch:create、~/.claude:create、~/.claude.json、~/.codex:create、~/.gemini:create、~/.config/opencode:create、~/.openclaw:create（flatpak/README.md:49、54-61）。文中还注明一个细节：Flatpak 的 :create 修饰符只对目录生效，~/.claude.json 不能带 :create；如果这个文件不存在，受限权限下应用可能建不出来，建议先跑一次 Claude Code，或者手工建一个内容为 {} 的空 JSON（flatpak/README.md:63）。

这里得说清一件事：这份权限清单直接对应 CC Switch 要读写的真实 CLI 配置文件，那些文件里存着你的 API Key。是给它整个 home 还是按清单收紧，取决于你自己的环境，本文不做建议。

顺带记一处冗余：release.yml 的 apt 安装列表里装了 flatpak 与 flatpak-builder（.github/workflows/release.yml:69-70），但整个文件里没有任何生成或上传 .flatpak 的步骤——在该文件里 grep flatpak 只命中这两行。这与 README 说的「官方 Release 不包含 Flatpak 包」并不冲突，只是工具链装了没用上。

装完之后：更新走哪条路

Tauri 配置里 bundle targets 设为 "all"，createUpdaterArtifacts 为 true（src-tauri/tauri.conf.json:38-39），自动更新配了两个 endpoint：https://dl.ccswitch.io/latest.json 与 GitHub releases latest 的 latest.json（src-tauri/tauri.conf.json:64-67）。README 声明该项目唯一官方网站是 ccswitch.io（README_ZH.md:15）。

也就是说，仓库里同时存在两条更新路径：应用自带的 updater，和包管理器（macOS 的 brew upgrade --cask cc-switch、Arch 的 AUR 包）。两条路各自的实际行为、会不会互相打架，仓库文档没有专门说明，我们也没有依据，不比。

一条按你自己处境走的选择路径

把上面的信息收一下，按你手上的机器倒推：

  • Windows x64：README 给了 msi 与 Portable zip 两个产物（README_ZH.md:359），两者分别适合什么场景仓库文档没有说明，按你自己的习惯选。下载后打不开先想到「解除锁定」。
  • Windows on ARM：README 和手册都没写，直接去 Releases 按 -Windows-arm64.msi 找。
  • macOS，已经在用 Homebrew：brew install --cask cc-switch 是 README 标推荐的那条；没在用 Homebrew 就下 .dmg。Intel 和 Apple Silicon 手册都标了支持。
  • Debian / Ubuntu：deb。Fedora / RHEL / openSUSE：rpm。其它发行版：AppImage，但先记住 CC_SWITCH_GDK_BACKEND 的存在。
  • Arch 系：paru -S cc-switch-bin 或 yay -S cc-switch-bin。
  • 只吃 Flatpak：官方不发，得自己按 flatpak/README.md 那三步从 deb 转。
  • 不管哪一条 Linux 路径：搜文件名时把架构那一段补上。

以上命令全部原样抄自仓库文档，我们没有在任何一台机器上执行过，请以官方文档与 Releases 页面的实际文件名为准。

你自己怎么把这处差异核一遍

三条命令的事，在你 clone 下来的仓库根目录执行：

sed -n '393,397p' README_ZH.md
sed -n '515,540p' .github/workflows/release.yml
sed -n '175,195p' docs/user-manual/zh/1-getting-started/1.2-installation.md

第一条看 README 给的三个包名，第二条看 CI 拼名字的那几行，第三条看用户手册的写法。三段并排放着，差异一眼就出来了。能复用的不是「Linux 包名带架构」这个结论，而是这个习惯：涉及下载文件名的文档，去 CI 脚本里对一遍再动手。 行号会随版本漂移，你重新 clone 之后以自己读到的为准。

最后重复一遍分寸：本文列出的差异都标了具体文件与行号，可以逐处核验；至于哪一处「才是对的」、为什么没同步，本文不做推断，也不拿它去评价这个项目——说完就停。

本文依据 CC Switch 官方仓库（github.com/farion1231/cc-switch）的 README、docs/ 下的用户手册与发布说明、 src/config/ 的预设定义与 src-tauri/src/ 的后端源码整理，核对日 2026-08-10，对应仓库快照 c39c903。 本文内容为仓库源码与文档口径，我们没有安装或运行过这个桌面应用， 因此不涉及界面外观、操作手感与切换速度的任何描述。 文中出现的阈值与默认值均为源码中的默认配置，不构成对实际运行结果的保证。 该项目仍在快速迭代，版本与默认值随时可能变动，请以仓库最新内容为准。 安全相关做法请结合自身环境评估，本文不构成安全方案建议。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员