ccgui跨平台构建与部署：macOS/Windows/Linux安装包制作、自动更新与发布全流程指南
【免费下载链接】desktop-cc-guiMulti-engine AI coding desktop client (Tauri). Claude Code, Codex, Gemini, OpenCode, DeepSeek Harness and more in one GUI.项目地址: https://gitcode.com/gh_mirrors/co/desktop-cc-gui
ccgui（桌面端多引擎 AI 编程客户端）基于 Tauri 2 构建，一套代码即可同时打包出 macOS 的 .dmg、Windows 的 NSIS 安装包和 Linux 的 AppImage/RPM，并内置 Tauri v2 自动更新机制。本文带你走通从本地打签名包到 CI 一键发布 latest.json 的完整流程，帮你零踩坑地完成跨平台部署 🚀
一、先认识构建体系：Tauri + pnpm 双栈
整个项目的前端（React + Vite + TypeScript）与后端（Rust）由 Tauri CLI 统一编排：
- 前端配置：package.json 中的
build:mac、dev等脚本 - 应用配置：src-tauri/tauri.conf.json 定义了产品名
CC GUI、版本号1.0.8、targets: "all"（全平台打包）以及createUpdaterArtifacts: true（自动生成更新签名产物）
一条命令即可开始：
- 开发调试：
pnpm dev（自动拉起 Vite + Rust 热重载） - 生产打包：
pnpm exec tauri build（按平台产出对应安装包）
二、macOS 安装包制作：签名 + 公证
macOS 是门槛最高的一站，核心是Developer ID 签名与notarization 公证两步。
2.1 本地一键签名构建
仓库自带脚本 scripts/build-signed-macos.sh，本地构建与 CI 使用同一稳定签名身份，保证 macOS TCC 权限（如桌面文件夹访问）在更新后不丢失：
- 准备
Developer ID Application证书（登录钥匙串） - 用
xcrun notarytool store-credentials建立公证凭据 - 执行
pnpm build:mac（或加SKIP_NOTARIZE=1仅签名不公证）
脚本最终调用tauri build --bundles app,dmg，并对产出的 DMG 执行notarytool submit+stapler staple完成公证装订。
2.2 为什么签名身份必须稳定？
脚本头部注释明确指出：稳定的 Developer ID 身份是「文件夹访问授权」在重建和自动更新后依然有效的前提。换证书 = 用户所有权限弹窗重来一次 ⚠️
三、Windows 安装包：NSIS + WebView2 引导器
Windows 侧通过 src-tauri/tauri.windows.conf.json 合并配置，关键点是webviewInstallMode采用embedBootstrapper（内嵌 WebView2 引导器），老机器无需额外联网安装运行时。
发布流水线 .github/workflows/release.yml 中 Windows 任务还会先跑cargo test：内置的 agent 目录哈希校验会在 CRLF 换行漂移时直接拒绝构建，确保发出的安装包不会带病上线。
产物为*-setup.exe+ 对应的.exe.sig更新签名文件。
四、Linux 双格式打包：AppImage 与 RPM
Linux 任务在ubuntu-24.04上依次产出两种格式：
- AppImage：
tauri bundle --bundles appimage，随后用 scripts/prune-appimage-wayland-libs.mjs 剔除内嵌 Wayland 库并重新签名，避免不同发行版 libwayland 版本冲突导致崩溃 - RPM：src-tauri/tauri.conf.json 中配置了 zstd 压缩，并声明
webkit2gtk4.1、gtk3等依赖，打包命令带 3 次重试以规避已知的压缩卡死问题
五、自动更新原理：latest.json 是怎么工作的
自动更新由 Tauri v2 updater 插件驱动，客户端配置见 src-tauri/tauri.conf.json 的plugins.updater：
pubkey：minisign 公钥，用于校验下载包的签名endpoints：指向 Release 页面中的latest.json清单
每次发版时，CI 会收集各平台的.tar.gz/.AppImage/-setup.exe及其.sig文件，按平台三元组（如darwin-aarch64、windows-x86_64）组装出latest.json。客户端后台轮询该清单，发现新版本即提示用户增量更新，全程无需手动重装。
踩坑提示：GitHub 会把资产名中的空格替换为点号，
latest.json必须指向「消毒后」的文件名，否则更新下载会 404 —— 这正是发布记录中修复过的经典问题（见 src/version/changelog.ts 的版本说明）。
六、一键发布全流程（CI Pipeline 拆解）
发布入口是手动触发的 .github/workflows/release.yml，只需输入一个版本号，流水线会自动完成以下 5 步：
| 步骤 | 作用 |
|---|---|
| 🛡️ preflight | 校验版本号格式、与配置文件一致、tag 未发布过 |
| ⚙️ 三平台并行构建 | macOS 双架构（arm64/x64）+ Linux + Windows |
| 📦 产物汇总 | 下载全部安装包、签名文件 |
| 📝 生成 latest.json | 自动聚合 commit 信息生成 Release Notes |
| 🚀 创建 Release | 上传全部资产，并发布版本号自增 PR |
发版后版本号还会自动进位（如 1.0.9 → 1.1.0），为下一次发布做好准备。
七、常见问题速查
Q1：本地构建 macOS 包总是提示未签名？需将TAURI_SIGNING_PRIVATE_KEY与密码注入环境（参考 scripts/build-signed-macos.sh 中的读取逻辑），密钥缺失时脚本会直接报错退出。
Q2：Linux AppImage 在某些发行版打不开？优先使用 CI 产出的「精简 Wayland 库后重新签名」的版本，本地自行打包容易遗漏 prune 步骤。
Q3：客户端收不到更新？检查三件事：latest.json是否存在于 Release、资产 URL 是否用了带点号的名字、endpoints与pubkey是否匹配当前发布通道。
掌握以上流程后，你就能独立完成 ccgui 在三大平台的构建、签名与自动更新发布了。想深入了解性能调优与诊断，可参考 docs/plans/2026-09-23-performance-fixes-and-diagnostics.md；更新功能的用户侧实现则位于 src/features/update/。
【免费下载链接】desktop-cc-guiMulti-engine AI coding desktop client (Tauri). Claude Code, Codex, Gemini, OpenCode, DeepSeek Harness and more in one GUI.项目地址: https://gitcode.com/gh_mirrors/co/desktop-cc-gui
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
