从零编译Ghostex源码:工具链、sccache缓存与10秒开发热循环完整搭建教程
从零编译Ghostex源码:工具链、sccache缓存与10秒开发热循环完整搭建教程
Ghostex 是一个完全基于 Rust 和 GPUI 构建的原生 Agents 工作台(原生 Agents 工作区),支持 20 多种 AI 编程代理(Claude Code、Codex、OpenCode 等),并内置 Ghostty 终端与移动端应用。这篇文章将带你从零编译 Ghostex 源码:配齐工具链、设置 sccache 编译缓存,并搭出约 10 秒一次改动的开发热循环。
一、Ghostex 源码仓库长什么样?
在动手之前,先快速了解你要编译的东西。整个仓库按「可交付物 / 库 / 服务端」组织:
| 目录 | 作用 |
|---|---|
| apps/desktop/ | Rust/GPUI 桌面应用(crate 名 ghostex-gpui),编译产物就是 Ghostex 应用本体 |
| server/ | gxserver 服务端 crate,产出 gxserver 与 ghostex CLI 两个二进制 |
| packages/ | 跨端共享库(聊天核心 gx-chat-core、设置目录等) |
| tooling/xtask/ | cargo xtask 任务工具,所有开发/构建命令的入口 |
| .dependencies/ | 外部依赖源码(Ghostty、code-server 等) |
桌面端编译完成并启动后,你会看到类似这样的界面:
二、Ghostex 源码编译工具链清单:一次装齐
Ghostex 本地构建需要以下工具,缺一不可(来源:CONTRIBUTING.md「Building from source」一节):
- ✅ Bun(JS 运行时与依赖管理,仓库锁定
bun@1.4.0) - ✅ Rust(rustup 安装即可)
- ✅ CMake + Ninja
- ✅ Zig 0.16(编译 Ghostty 与 zmx 终端守护进程需要)
- ✅ sccache(编译缓存,详见下一节)
关键细节:Rust 版本是锁死的
桌面 crate 与 gxserver 都在各自的 rust-toolchain.toml 中锁定 Rust 1.95.0:
rustup 会在你进入对应目录时自动切换工具链,无需修改你的全局默认版本。两个文件刻意保持同一版本,是为了让共享的 sccache 缓存命中(版本不一致意味着缓存全废)。
💡 Windows 用户:额外安装 Git for Windows、Node.js、Visual Studio Build Tools(含「Desktop development with C++」工作负载)与 Windows SDK,然后用一条命令搞定前置准备:
cargo xtask setup-windows(自动安装固定版 Rust 工具链、下载 Zig 0.16.0 到build/toolchains/、安装 sccache)。
三、克隆仓库并安装依赖
克隆源码:
git clone https://gitcode.com/gh_mirrors/gh/Ghostex
cd Ghostex
安装 JavaScript 依赖(用于构建内嵌页面与检查脚本):
bun install --frozen-lockfile
⚠️ 使用
--frozen-lockfile确保依赖版本与仓库锁文件完全一致。
四、sccache 缓存配置:Ghostex 编译速度的核心
为什么 sccache 是「硬性依赖」而不是可选优化?
桌面与 server 两个 crate 的构建配置都写死了 rustc-wrapper = "sccache":
它的价值在于:每个依赖 crate(gpui、tokio、CEF 等)只按「源码+编译参数」编译一次,之后全部从本地磁盘缓存回放——即使你执行了 cargo clean 也是如此。如果机器上没装 sccache,cargo 会直接报错 could not execute process 'sccache',而不是默默降级。
安装 sccache
# macOS
brew install sccache
# 或通用方式
cargo install sccache
配置缓存位置与大小
sccache 的服务器是常驻守护进程,只在启动时读取一次配置,所以先写配置、再停掉旧进程:
-
创建用户级配置文件:
- macOS:
~/Library/Application Support/Mozilla.sccache/config - Linux:
~/.config/sccache/config
内容示例(将 20 GiB 调大默认 10 GiB 的缓存上限):
[cache.disk] dir = "~/Library/Caches/Mozilla.sccache" size = 21474836480 - macOS:
-
停止旧服务让新配置生效,并验证状态:
sccache --stop-server sccache --show-stats # 构建后运行可看到命中统计
📦 小贴士:仓库提供 tooling/clean-build-caches.py 预览/清理过期构建缓存(macOS),避免
target/目录无限膨胀。
五、一条命令启动:cargo xtask start 的 10 秒热循环
Ghostex 把所有开发命令统一收口到 cargo xtask(别名定义在根目录 .cargo/config.toml,实现在 tooling/xtask/)。运行 cargo xtask help 可查看全部命令。
构建并启动桌面应用
cargo xtask start
它会完成:编译 Rust 二进制 → 准备运行时组件(zmx、code-server 等)→ 打包并签名应用 → 同步安装并启动。首次构建较慢,之后进入热循环模式:在维护者的 M5 Pro 上实测,仅改一行 Rust 代码,重新构建+重启约 10 秒;完全无改动时构建半程仅约 5 秒(完整数据见 ai/local-start-performance.md)。
常用参数一览
| 命令 | 用途 |
|---|---|
cargo xtask start --optimized |
用完整优化(opt-level 3)重建,测性能前必加 |
cargo xtask start --build-only |
只计时构建半程,不安装不启动 |
cargo xtask start --debug-info |
为崩溃调试生成符号信息(默认关闭) |
cargo xtask start-server |
macOS 专属:只重编 gxserver 并热替换,窗口不关、会话不断 |
cargo xtask start --prepare-only |
只重复源码准备,不启动应用(Windows) |
🚀 为什么默认构建这么快?桌面 crate 与 gxserver 本地启动时以 opt-level 0 编译(依赖库仍全量优化),冷编译 CPU 耗时从 315 秒降到 71 秒——但正因如此,不要拿默认启动来评判应用性能。
编译完成的应用里,你可以在聊天框直接切换 20+ 种代理:
六、顺手体验:Web 构建与检查命令
Ghostex 的浏览器版就是桌面端 GPUI 源码编译到 wasm(位于 apps/gpui-web/):
cargo xtask start-web # 构建并用 ghostex web 在 :4173 提供页面
cargo xtask web-dev # 构建 wasm 并运行 Vite 开发服务器 :4174
改动 TypeScript 代码后,用这两个门禁做类型检查:
cargo xtask typecheck # 根级 TS 门禁(shared、core-ui 等)
cargo xtask desktop-typecheck # 覆盖 apps/desktop/sidebar 与 views
七、新手高频踩坑清单
| 现象 | 原因与解法 |
|---|---|
could not execute process 'sccache' |
未安装 sccache;brew install sccache。不要删除 config.toml 里的 wrapper 配置绕过 |
用 --manifest-path 从仓库根运行 cargo 报错 |
桌面 crate 必须进入 apps/desktop/ 目录内再运行 cargo,否则工具链锁定不生效 |
Windows 下 start 后应用装到 %LOCALAPPDATA%\Ghostex\current |
这是设计行为(与发布安装器同路径);想留在 checkout 内可设 GHOSTEX_INSTALL_DIR 指向 build\local |
改完 server/ 想快速验证 |
用 cargo xtask start-server(macOS)热替换,只重启守护进程,zmx 会话保持存活 |
| 想确认构建行为细节 | 先读 ai/local-start-performance.md,里面记录了每项提速决策与被否决的方案 |
八、延伸阅读:源码里的「编译知识地图」
- CONTRIBUTING.md —— 官方「Building from source」章节,各平台安装步骤的权威来源
- ai/local-start-performance.md —— 10 秒热循环的实测数据、opt-level 决策与拒绝过的替代方案
- tooling/xtask/src/main.rs ——
cargo xtask全部命令清单与参数说明 - server/rust-toolchain.toml —— 为什么要与桌面 crate 锁定同一 Rust 版本
- apps/desktop/scripts/ —— macOS 打包、签名、CEF 分发的底层脚本
装好工具链、配好 sccache 之后,cargo xtask start 就是你日常开发的全部入口。改一行代码,约 10 秒后新应用已在眼前——这就是 Ghostex 源码编译的完整体验。🎉


