GPUI 开发规范与辅助

GPUI 是 Zed 团队开发的 hybrid（immediate + retained）GPU 加速 Rust UI 框架。本技能沉淀其标准开发模式、生态选型与排错经验。

使用前必做的背景核验

GPUI 生态在 2026 年处于分裂期，动笔前先确认用户项目实际用的"哪一支 GPUI"：

crates.io gpui 0.2.x：发布线停在 0.2.2（2025 年底），此后 Zed 官方暂停了 GPUI 独立化节奏（2026 年初社区确认）。API 以 0.2.x 文档为准，不要把 Zed main 分支的新写法教给 0.2.x 项目。
Zed 仓库 main 分支（zed/crates/gpui + gpui_platform）：与 0.2.x 已显著分叉（如 2025 年初 View/ViewContext/WindowContext 已合并为 Entity/Context<T> + Window），pre-1.0、breaking change 频繁。
longbridge 生态：gpui-kit 0.8 / gpui-component 0.8 / gpui-fast 0.1.10。 ⚠️ gpui-kit 依赖的 gpui 是 crates.io 上的 gpui-pre 0.3.9（Cargo.toml 里写 package = "gpui-pre"），不是 crates.io 的 gpui 0.2.2。两套类型互不兼容，严禁混用。 gpui-kit 重导出 pub use ::gpui::*;，所以代码写 use gpui_kit::{...} 而非 use gpui::{...}。
社区变体：Glass-HQ/gpui、gpui-unofficial 等。

判断方法：看用户 Cargo.toml 的 gpui 来源（版本号 / git rev / path 依赖 / package = "gpui-pre"）。 同一个项目里禁止混用不同分支——类型互不兼容。

选型路径

| 场景 | 推荐 | 说明 | |---|---|---| | 最小依赖/库作者/想完全掌控渲染层 | 裸 gpui（或 gpui+gpui_platform） | 官方 primitives，无组件库 | | 常规业务桌面应用（表单/表格/弹窗/主题） | gpui-kit 0.8（聚合 component + base + assets） | 生态最成熟，60+ 组件，17k+ star | | 只要无头交互组件（自己出样式） | Base GPUI / Bezel / guise | 见 references/ecosystem.md | | 视频播放、移动端为主、重度无障碍 | 劝退，建议换框架 | GPUI 多媒体仅 macOS 成熟；gpui-mobile 未成熟；a11y 弱于主流框架 |

三条会毁掉编译时间的铁律

一律 use gpui::prelude::*;（gpui-kit 路线写 use gpui_kit::prelude::*;）。 Render IntoElement Styled ParentElement InteractiveElement StatefulInteractiveElement AppContext FluentBuilder 都在里面。少导一个 → 几十个 no method named xxx found for struct gpui::Div。 trait 没进作用域，方法就等于不存在。
.on_click() 必须先 .id()：.id() 把 Div 变成 Stateful<Div>，on_click 定义在 StatefulInteractiveElement 上，Div 本体没有。
cx.spawn 闭包必须写成 async 闭包：写 cx.spawn(move |this, cx| async move { ... }) 会报 implementation of AsyncFnOnce is not general enough。正确：cx.spawn(async move |this, cx| { ... })。

核心心智模型（写代码前必须对齐）

三种 register：

Entity<T>：状态容器，句柄类似 Rc，数据归 App 所有。跨组件共享状态一律用它。
View：实现了 Render trait 的 Entity。每帧 GPUI 调 render() 产出元素树——状态变化通过 cx.notify() 触发重渲染，不是在 render 里 new 对象。
Element：低层命令式（prelayout/paint 自定义），只在做大列表虚拟化、代码编辑器级布局、自定义绘制时才实现。

Context 体系（详见 references/apis.md 第 2 节）：

App：全局根 context；Context<T>：实体内 context，可 deref 成 App。
Window 不是 context，操作全局状态需额外传 &mut App。
跨 await 必须 to_async 出 AsyncApp/AsyncWindowContext，此后所有实体访问变 fallible（实体可能已释放）。

状态更新三条铁律：

改完状态必须 cx.notify()，否则界面不刷新。
子 Entity 句柄必须存放在父结构体字段里，局部变量会被 drop。
Entity::clone() 只复制句柄不复制数据；handler 里用 entity.update(cx, |this, cx| ...)，别在 handler 参数里拿 &mut。

⚠️ 0.2.2 里 App::update / Context::update 是 pub(crate)，外部 crate 调不到。改自己的实体用 entity.update(cx, ...)（Entity 上的公开方法）。

键盘优先范式：功能先定义成 Action（actions! 宏），元素上 on_action + key_context("name")，键位写在 keymap JSON（action 用全限定类型名寻址）。鼠标只是 action 的第二入口。

标准工作流

确认分支与版本（见上），选定依赖写法。新建项目直接取 assets/templates/main_minimal.rs（gpui 0.2.2）或 assets/templates/main_gpui_component.rs（gpui-kit 0.8）——两个模板均已实测编译并运行通过。
搭骨架：main() 里 Application::run（0.2.x）或 gpui_platform::application().run（git main）或 gpui_kit::application().run（组件库）→ cx.open_window → 根 view cx.new。用组件库则必须先 init(cx)，窗口必须用库提供的 open_window（包 Root，否则 dialog/menu/notification 不工作）。
写 view：struct + impl Render，链式 div() 样式 API 布局。API 速查在 references/apis.md。
加交互：点击 → on_action/带 id 的 on_click；快捷键 → Action + assets/templates/keymap.json；异步 → cx.spawn（async 闭包）/ cx.spawn_in（绑窗口）；阻塞 IO → cx.background_executor().spawn(...)。
平台依赖自检：macOS 必须 Xcode + cmdline tools + Metal；Linux 必须 wayland/x11 feature 之一；Windows 免 feature 但复杂 UI 建议 8M 栈（.cargo/config.toml）。
测试：#[gpui::test] + TestAppContext 模拟输入；纯逻辑（文件遍历/数据处理）直接写普通 #[test]，不起渲染栈。
排错：对照下方错误表；仍无解就读 Zed 源码同类实现或 gpui-kit 仓库的 examples。

常见报错与排查

| 症状 | 根因 | 处置 | |---|---|---| | 几十个 no method named xxx found for struct gpui::Div | trait 没导入——Styled/ParentElement/InteractiveElement/AppContext/FluentBuilder 都不在作用域 | use gpui::prelude::*;（gpui-kit 写 use gpui_kit::prelude::*;）。这是最高频误判：不是 API 不存在，是 trait 没进 scope | | cannot find trait Render / IntoElement in this scope | 同上，prelude 没导 | use gpui::prelude::*; | | no method named on_click found for struct gpui::Div | .on_click 需要 Stateful<Div> | 先 .id("...") 再 .on_click(...) | | implementation of AsyncFnOnce is not general enough | cx.spawn 写成了 move \|a, b\| async move {} | 改 async 闭包：cx.spawn(async move \|this, cx\| { ... }) | | cannot find type WeakView in crate gpui | 0.2.2 里叫 WeakEntity | gpui::WeakEntity<T> | | method 'update' is private | 0.2.2 里 App::update/Context::update 是 pub(crate) | 用 entity.update(cx, ...) 或 cx.entity().update(cx, ...) | | borrowed data escapes outside of function（SharedString::from(&str)） | 局部 &str 非 'static | 先 .to_string().into() | | cannot find module or crate gpui（组件库项目） | gpui-kit 用 gpui-pre 重命名，用户项目里没有 gpui crate | 全部改成 use gpui_kit::{...} + use gpui_kit::prelude::*; | | mac 链接报 Metal/core_graphics 错误 | 未装 Xcode 或 xcode-select 没指向 Xcode | xcode-select --install；sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer | | 界面文字全部不可见/方块 | mac 未开 font-kit feature，落到无字形 fallback | gpui_platform 加 features = ["font-kit"] | | Linux 起不来/无窗口 | 未启用任何 windowing backend | 加 features = ["wayland", "x11"] | | Windows 深 UI 树栈溢出崩溃 | 默认栈太小 | 项目 .cargo/config.toml 设 rustflags = ["-C", "link-arg=/STACK:8388608"]（gpui-kit 同款做法） | | 点了没反应/状态变了 UI 不更新 | 忘 cx.notify()，或 notify 的对象不是渲染中的那个 Entity | 检查 update 与 notify 是否在同一个 entity 的 Context 上 | | 状态莫名每帧重置 | 在 render() 里 cx.new 创建子 view | 把子 Entity 创建移到构造/handler，句柄存字段 | | 跨 await 后 panic/编译拒绝 | 直接持有 &mut Context 跨 await | cx.to_async()，并对 fallible 访问做降级处理 | | 升级 gpui 后 ViewContext 等类型不存在 | 2025-01 起 View→Entity、ViewContext/WindowContext→Context<T>+Window 大重构 | 按新 API 迁移；或锁回 0.2.x | | 依赖解析冲突 / 两套 gpui 类型不匹配 | 混用了 crates.io 0.2.x 与 git/fork/gpui-pre 分支 | 统一 [patch] 或直接依赖同一来源，全 workspace 对齐 | | keymap 不生效 | context 名或 action 全限定路径写错 | "up": "menu::MoveUp" 必须与 key_context 名 + 模块路径逐字一致 | | 窗口标题栏显示 Windows 默认图标，但 exe 图标是对的 | .rc 里用了 IDI_ICON ICON 而非 1 ICON —— IDI_ICON 是 MAKEINTRESOURCE(1) 的宏，rc.exe 求值不出整数 ID，当成命名资源，导致 group icon 拿不到 ID 1，gpui 的 LoadImage 返回 0 | 改成 1 ICON "app.ico"。详见 references/apis.md 第 7.1 节 | | 资源编译报 no method named unwrap found for CompilationResult | embed-resource 3.x 的 compile() 返回枚举不是 Result | 调 .manifest_required() 再 .expect() | | 自己的 .rc 嵌 manifest 后链接期冲突 | gpui 自身已嵌 RT_MANIFEST ID 1（feature windows-manifest 默认开启） | 别再嵌，或关掉 gpui 的该 feature，二选一 |

Windows 打包速查

gpui 0.2.2 在 Windows 上的两件常事，细节见 references/apis.md 第 7.1 节：

不弹控制台 —— src/main.rs 顶部：

#![cfg_attr(all(target_os = "windows", not(debug_assertions)), windows_subsystem = "windows")]

Release → PE subsystem 2（GUI）；Debug → 3（Console）保留 panic 输出。 Release 无 stderr，panic 会静默消失 —— 用 catch_unwind 包住启动流程并弹原生 MessageBox。

应用图标 —— resources/app.rc + app.ico，build.rs 用 embed-resource 编译：

1 ICON "app.ico"     // 必须整数 1，不能写 IDI_ICON

规范约定（给用户的代码审查清单）

每个文件顶部 use gpui::prelude::*;（或 gpui-kit 版）——不许手工挑 trait。
视图按功能分模块：views/（Render 实体）、components/（无状态 Element/RenderOnce 复用件）、actions.rs（全部 Action 定义）、assets/（SVG/字体/keymap）。
Action 集中定义、命名空间化（mod xxx { actions!(gpui, [A, B]); }），不散落。
主题色/字号从统一 Theme/常量取，不硬编码 rgb；用组件库则走它的 theme JSON。
大列表必须虚拟化（LazyList / 组件库 List），禁止每帧重建全量子树。
每个 view 的对外消息用 emit + observe，父级订阅，不做反向全局单例。
锁版本：Cargo.toml 用精确 rev 或精确版本号（gpui = "=0.2.2"）；升级 gpui 视为一次专项迁移。

详细资料索引

API 速查与代码范式：references/apis.md
生态、组件库、参考项目、学习路径：references/ecosystem.md
可运行模板（均已实测）：assets/templates/

来源时效声明

本技能事实核验于 2026-10（gpui.rs、zed/crates/gpui README、docs/contexts.md、docs/key_dispatch.md、awesome-gpui、gpui-kit/gpui-component 仓库）。 2026-10-20 增量核验：在 Windows 上用 crates.io gpui = 0.2.2 与 gpui-kit = 0.8.0 各建了一个工程，两个模板均实际编译并启动运行通过；本文所有「实测」条目即来自这两轮验证。 GPUI 生态变化快，涉及具体 API 签名时以用户项目锁定版本的源码与 docs.rs 为准，不确定就打开对应仓库文件核对后再写代码——别照抄本文，照抄之前先让编译说话。