Zed 源码开发指南：从平台构建到开发期密钥、性能测量与 ETW 剖析

Zed（“Code at the speed of thought”）是一个高性能、多人在线协作的代码编辑器。本篇技术指南以仓库 docs/src/development.md 为主线，系统讲解三块内容：如何在 macOS / Linux / Windows 上从源码构建 Zed；为何开发构建默认绕过系统钥匙串（Keychain）以及如何强制启用；如何借助 ZED_MEASUREMENTS 环境变量、script/histogram 对比工具与 util_macros::perf 宏测量帧渲染性能，并介绍了 Windows 上基于 ETW 的 CPU/GPU/内存/I/O 剖析流程。读完你既能独立完成跨平台源码构建与调试，也能用仓库自带的一套测量基建对 Zed 的渲染与进程性能做量化对比。

概览：一份“开发 Zed”的引导页

development.md 本质上是 Zed 开发文档的入口页，它把内容拆成两条主线：

1. 平台专属构建指南：文档明确将读者导向 macOS、Linux、Windows 三份分平台文档（对应仓库路径 docs/src/development/macos.md、docs/src/development/linux.md、[docs/src/development/windows.md)），按需选择即可。
2. 跨平台的开发期实践：包括开发构建的钥匙串访问策略（Keychain access）、帧时间测量系统（Performance Measurements）、Windows 上的 ETW 剖析，以及面向贡献者的崩溃调试与行为规范入口（docs/src/development/debugging-crashes.md、CONTRIBUTING.md）。

下面先快速过一遍三平台构建要点，再深入剖析三个开发期工具的底层实现。

在 macOS 上构建

完整步骤见 docs/src/development/macos.md，下面是与文档一致的可执行主线。

依赖安装：先通过 rustup 安装 Rust 工具链；再从 App Store 或 Apple Developer 网站安装 Xcode（安装后需启动一次并确认 macOS 组件），随后执行：

xcode-select --install
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

由于 wasmtime-c-api 等依赖需要，还需安装 cmake：

brew install cmake

构建与测试（使用 Cargo）：

cargo run          # 调试构建
cargo run --release # 发布构建
cargo test --workspace

可视化回归测试（macOS 专属）：Zed 内置可视化回归测试，会抓取真实窗口截图并与基线图对比，因此需要为终端授予“屏幕录制（Screen Recording）”权限——先运行一次测试触发系统授权弹窗，或在“系统设置 > 隐私与安全性 > 屏幕录制”中手动开启终端应用权限并重启终端。运行方式：

cargo run -p zed --bin zed_visual_test_runner --features visual-tests

基线图在本地生成（文档注明其被 gitignore 以避免撑大仓库）：改动 UI 前先从已知良好状态生成基线 git checkout origin/main && UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests && git checkout -；改动 UI 后若行为是有意为之，再执行同样命令刷新基线。

采样已发布构建的 CPU 热点：正式发布的 macOS 二进制剥离了局部符号，需要靠每个 release 归档在 Sentry 的 zed.dwarf 做符号化。现场用 sample Zed 10 -f zed-sample.txt 采样，并用命令面板中的 zed: About 记录精确版本与 commit；事后用 atos -o zed.dwarf -l <load address> <address...> 解析地址，或把 dwarf 组装为 Zed.dSYM/Contents/Resources/DWARF/zed 后让 sample 自动解析出文件与行号。

常见排障：Metal shader 编译失败时执行 sudo xcode-select --switch 指向 Xcode；macOS 26 上可尝试 xcodebuild -downloadComponent MetalToolchain。遇到 'dispatch/dispatch.h' file not found 时除修复 xcode-select 路径外，还需导出 BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)" 并 cargo clean 后重编。测试报 “Too many open files (os error 24)” 可用 cargo install cargo-nextest --locked 后改用 cargo nextest run --workspace --no-fail-fast。

在 Linux 上构建

完整步骤见 docs/src/development/linux.md。

安装 rustup 后，系统依赖可用仓库自带的 script/linux 一键安装（需要手动安装时可参考该脚本内的包清单）：

script/linux
cargo run          # 编辑器调试构建
cargo test --workspace

发布模式下 Linux 的主要用户界面是 cli crate，开发期运行 cargo run -p cli。如需安装本地构建，script/install-linux 会以 release 模式构建 zed 与 cli，将二进制安装到 ~/.local/bin/zed，并把 .desktop 文件安装到 ~/.local/share。

窗口系统：Zed 同时支持 X11 与 Wayland，运行时自动探测；若在 Wayland 会话中想强制 X11 模式，可设置 WAYLAND_DISPLAY=''。

面向发行版打包商的要点：需要同时产出两个二进制——把 crates/cli 以 zed 命名放入 $PATH，把 crates/zed 放到 $PATH 上层目录的 libexec/zed-editor（或 lib/zed/zed-editor）；.desktop 文件模板与自动更新禁用可通过 ZED_UPDATE_EXPLANATION 环境变量实现（例如 ZED_UPDATE_EXPLANATION="Please use flatpak to update zed."）。仓库还提供 Flatpak 本地构建流程：先按平台文档安装 Flatpak 并运行 script/flatpak/deps，再执行 script/flatpak/bundle-flatpak，产物位于 target/release/{app-id}.flatpak。

内存/CPU 剖析：内存泄漏排查推荐 heaptrack（cargo install cargo-heaptrack 后用 cargo heaptrack -b zed 启动，退出后按提示用 heaptrack_interpret 转换并交给 heaptrack_gui）；CPU 热点用 Linux perf 抓取 sudo perf record -g --call-graph dwarf -p <pid>，由于 release 二进制被 strip，须用 perf buildid-cache -v -a <release binary> 注入符号、perf inject -i perf.data -o perf_with_symbols.data 合并后，用 cargo install cargo-flamegraph 提供的 flamegraph --perfdata perf_with_symbols.data 生成火焰图（从源码层面看，这就是 script/bundle-linux 会归档未 strip 二进制的配套用法）。

在 Windows 上构建

完整步骤见 docs/src/development/windows.md。

依赖包括 rustup、Visual Studio（或轻量的 Build Tools），需勾选 MSVC x64/x86 构建工具与 Spectre-mitigated 库，并安装不低于 Windows 10 SDK version 2104 (10.0.20348.0) 的 SDK 以及 CMake。文档给出了可直接导入 Visual Studio Installer 的组件清单（含完整版与 Build Tools 版两套 JSON），适合在 CI 中复现环境。

构建与测试命令与另外两平台一致（cargo run / cargo run --release / cargo test --workspace），可视化回归测试目前仅限 macOS。Windows 平台还有一些值得注意的坑：

• 不要用 RUSTFLAGS 覆盖构建：Zed 依赖仓库 .cargo/config.toml 中的 rustflags（如 -C symbol-mangling-version=v0、--cfg tokio_unstable、Windows 目标上的 windows_slim_errors 与 +crt-static）。需要追加参数时，应在 .cargo/config.toml 中扩展或在仓库父目录放一份独立配置。
• STATUS_ACCESS_VIOLATION：若使用 rust-lld.exe 链接器触发，换用其他链接器。
• RC 路径错误：报 “Selected RC path: 'bin\x64\rc.exe'” 时手动设置 ZED_RC_TOOLKIT_PATH 指向 Windows Kits 的 ...\bin\<SDK_version>\x64。
• 路径过长：分别用 git config --system core.longpaths true 与注册表 LongPathsEnabled=1 开启长路径支持后重启。
• 图形问题：Windows 上 Zed 使用 Vulkan 渲染，启动失败且日志（C:\Users\YOU\AppData\Local\Zed\logs\Zed.log）出现 NoSupportedDeviceFound、ERROR_INITIALIZATION_FAILED、GPU Crashed 等时，优先更新显卡驱动；文档同时提示 Zed 目前与 Bandicam 不兼容。

开发构建为何绕过系统钥匙串：Keychain access 的取舍与开关

Zed 把各类密钥统一存放在操作系统钥匙串中，这对正式发布版完全成立。但开发构建在 macOS 上没有稳定身份，即使选择 “Always Allow”，只要二进制发生任何变化，系统仍会反复弹出要求输入密码的钥匙串授权框，严重拖慢迭代节奏（相关说明见 docs/src/development.md）。

因此，默认情况下开发构建会改用开发专用凭证提供者（Development Credentials Provider）来旁路系统钥匙串。这一设计与源码完全一致：在 crates/zed_credentials_provider/src/zed_credentials_provider.rs 的 new() 中，只有 ReleaseChannel::Dev 时才可能走开发提供者，其余频道（Nightly / Preview / Stable）无条件使用系统钥匙串。也就是说，开发期的旁路行为只作用于开发构建，这与文档中的强调一致：

这仅仅适用于开发构建；所有非开发 release 频道始终使用系统钥匙串。

开发提供者的底层实现（crates/zed_credentials_provider/src/zed_credentials_provider.rs）是把凭证以 JSON 形式明文写入 config_dir()/development_credentials 文件——源码注释明确警告这不是安全存储，仅限开发使用，其存在纯粹是为了绕开反复授权钥匙串的痛点。若你确需在开发构建中测试真实的系统钥匙串路径，可设置：

ZED_DEVELOPMENT_USE_KEYCHAIN=1

该开关的读取逻辑位于 crates/zed_credentials_provider/src/zed_credentials_provider.rs：只要该环境变量存在且非空（is_ok_and(|value| !value.is_empty())）即视为开启，且其在非 Dev 频道是 no-op——即便你在正式版里设置它也不会有任何效果。

帧时间测量系统：用 ZED_MEASUREMENTS 量化渲染性能

Zed 内置了一套帧时间测量系统，用于统计每一帧渲染所花费的时间，在“不同版本间对比渲染性能”或“优化帧渲染代码”场景下尤为实用。

开启测量：ZED_MEASUREMENTS

启用方式非常简单：

export ZED_MEASUREMENTS=1

开启后，Zed 会把每帧渲染耗时打印到 stderr。其底层实现可在 crates/gpui_util/src/lib.rs 的 measure() 函数中看到全貌：ZED_MEASUREMENTS 首次读取时解析一次并缓存到 OnceLock<bool>，其取值既接受 1 也接受 true；开启后对传入的闭包计时，最终以 eprintln!("{label}: {elapsed:?}") 输出到 stderr，未开启则零开销直接执行闭包。

版本对比工作流：script/histogram

文档给出了一套完整的两版本帧渲染性能对比流程（script/histogram 位于仓库 script/histogram）：

1. 开启测量：

   export ZED_MEASUREMENTS=1
   

2. 测试第一个版本：检出想测量的 commit，以 release 模式运行 Zed 并正常使用 5–10 秒，把输出重定向到文件：

   cargo run --release &> version-a
   

3. 测试第二个版本：检出要对比的另一 commit，重复上一步：

   cargo run --release &> version-b
   

4. 生成对比结果：

   script/histogram version-a version-b
   

script/histogram 可接收任意数量的测量文件，并将这些版本之间的帧渲染耗时数据生成为直方图可视化，便于直观看出改动带来的帧时间分布变化。

基准化单元测试：util_macros::perf + cargo perf-test

针对单元测试级别的基准，文档推荐使用 util_macros crate 提供的 #[perf] 属性：给测试函数标注 #[perf] 后，运行：

cargo perf-test -p $CRATE

即可对指定 crate 的这些标注测试执行基准测量。#[perf] 的用法与可扩展的示例见 crates/util_macros 与 tooling/perf 两个 crate 的 rustdoc（仓库内对应 crates/util_macros、tooling/perf），这是把“帧时间对比”扩展到“任意代码段计时”的通用入口。

Windows 上的 ETW 剖析：record / save / cancel 三段式流程

Zed 支持通过 Windows 的 Event Tracing for Windows（ETW）做性能剖析，可捕获 CPU、GPU、内存、磁盘与文件 I/O 等详细数据，产物保存为 .etl 文件，可用标准剖析工具打开分析。需要特别留意的是，ETW 记录可能包含个人身份或安全敏感信息（如访问过的文件路径、注册表键、进程名），与他人分享 trace 前应做好脱敏。

开启录制的入口在命令面板（Command Palette），两个命令：

• zed: record etw trace —— 记录 CPU、GPU、内存与 I/O 活动；
• zed: record etw trace with heap tracing —— 额外包含 Zed 进程的堆分配数据。

随后 Zed 会请求管理员权限，授权通过即开始录制。录制过程中，可随时通过命令面板执行：

• zed: save etw trace —— 停止录制并把 trace 保存到磁盘；
• zed: cancel etw trace —— 停止录制且不保存。

从源码看，这四个命令在 crates/etw_tracing/etw_tracing.rs 中以 actions! 宏定义（RecordEtwTrace、RecordEtwTraceWithHeapTracing、SaveEtwTrace、CancelEtwTrace），该 crate 顶部以 #![cfg(target_os = "windows")] 限定为 Windows 专属，内部通过 socket 与 Windows Performance Recorder（wprcontrol）协同工作，并由 crates/zed/src/main.rs 中的 etw_tracing::init(cx) 在启动时接入 Zed 的全局状态。录制中的会话状态机（Recording / ChoosingOutputPath / Stopping）与全局会话句柄也都在该文件中实现，drop 时会清理临时 socket 文件，保证不残留。

崩溃调试与其他贡献者资源

进一步深入开发 Zed 时，下列仓库内资源可作为延伸入口：

• docs/src/development/debugging-crashes.md：定位与分析 Zed 崩溃的专项指南（development.md 作者链接区首推文档）。
• CONTRIBUTING.md：仓库根目录的贡献规范，包含代码风格、提交流程与 PR 预期。
• crates/zed：编辑器主 crate（zed 二进制与构建脚本所在）。
• docs/src/development：完整的开发文档集，除三平台构建指南外还收录了 glossary、release-notes、feature-process 等。

总而言之，Zed 的开发基建贯穿“构建—日常迭代—性能量化—疑难剖析”全链路：三平台构建文档给出可直接复制的环境准备与命令；ZED_DEVELOPMENT_USE_KEYCHAIN 与开发凭证提供者解决开发构建被钥匙串弹窗打断的痛点；ZED_MEASUREMENTS、script/histogram 与 #[perf] 提供了从帧级别到函数级别的统一测量手段；ETW 集成则把 Windows 上的进程级剖析（含堆追踪）收敛为命令面板里四个动作。掌握这些工具后，无论是对比渲染改动、定位 CPU/内存热点，还是为 Zed 提第一个 PR，你都有了明确的起点与可验证的抓手。