GPUI 实战教程：用 Rust 构建高性能桌面应用

这套教程基于 HiPoster 项目整理而成。原项目既是一个 GPUI 学习样例，也是一个用 GPUI 开发的 HTTP 请求调试桌面软件；这里将它重新组织为一套更完整的 GPUI 教程，既覆盖框架核心概念，也保留真实应用里的工程取舍。

版本状态

本文档更新于 2026-07-06，版本基准以 GitHub 上 zed-industries/zed 的 main 分支为准。当前检查到的 zed main 提交为 04de6dab7c890d815e316f2f9554f9eeeaf8ebb2，HiPoster 本地锁定的提交为 7a8f13902982b087e6e27e4d105e9595b26b9429，所以教程会同时标明“最新 GPUI 写法”和“HiPoster 现有实现”之间的差异。

• GPUI 官网 与 Zed 仓库中的 GPUI README
• GPUI Contexts 官方说明
• GPUI Key Dispatch 官方说明
• Zed 仓库中的 GPUI examples
• GPUI Component Getting Started
• HiPoster 源码：Cargo.toml 中使用 gpui、gpui_platform、gpui-component、reqwest、tokio、serde、directories

GPUI 仍处于 pre-1.0 阶段，API 会随 Zed 编辑器开发继续变化。crates.io 与 docs.rs 上的发布版可能落后于 Zed 主仓，本教程不把它们作为版本依据；即使官方 README 中出现 gpui = { version = "*" } 这样的发布版写法，实际项目也建议改用 GitHub zed-industries/zed 的 main 或固定 rev。升级时按本教程的检查清单逐章验证入口、上下文、事件、组件库和打包脚本。

学习路线

1. 生态、安装与第一个窗口
2. 项目架构：从模型到视图
3. 应用入口、窗口与生命周期
4. 元素、布局与组件库
5. 状态管理、Entity 与通信
6. Action、快捷键、菜单与输入
7. HTTP 请求工具实战
8. 异步任务与 UI 安全
9. 持久化、主题与资源
10. 性能、测试与跨平台发布

你会学到什么

• 如何启动一个独立 GPUI 应用，并把根视图绑定到窗口。
• 如何用 Render、IntoElement、Entity<T>、Context<T> 组织界面与状态。
• 如何用 GPUI Component 快速搭建按钮、输入框、Tab、可拖拽分栏、滚动区域和标题栏。
• 如何把一个 HTTP 调试器拆成模型层、网络层、状态层、视图层、持久化层与构建脚本。
• 如何处理异步请求、历史记录、主题切换、JSON 格式化、脏标记优化、测试与跨平台打包。

示例应用：HiPoster

HiPoster 的核心功能包括：

• 多 Tab 请求编辑。
• URL 查询参数、Header、Body、Form Data、Urlencoded、Bearer 和 Basic Auth。
• reqwest + tokio 异步发送请求。
• 响应状态、耗时、大小、Header、Pretty/Raw Body 展示。
• 请求历史记录和主题配置持久化。
• 通过 gpui-component 使用按钮、菜单、输入框、Tab、Resizable、Spinner、TitleBar 等组件。

整套教程的目标不是把 HiPoster 原样抄一遍，而是把其中可复用的 GPUI 心法沉淀出来：把状态放在清楚的位置，让 UI 只做渲染，把阻塞工作扔到异步任务里，再用工程化手段把应用交付出去。