Zed 源码开发指南：在 macOS / Linux / Windows 上安装、构建与测试这款高性能编辑器

Zed 是由 Atom 与 Tree-sitter 团队打造的 Rust 编写的高性能多人协作代码编辑器。本文基于仓库根目录 README 与配套的三份平台构建文档，系统讲清楚从获取源码、安装各平台构建依赖，到调试构建、发布构建、运行全量测试的完整流程，并深入解析仓库中的工具链配置、Cargo 工作区配置与开源许可合规机制，帮助你在本地搭建出一个可贡献代码的 Zed 开发环境。

项目定位与仓库结构

README 开篇即说明了 Zed 的身份："a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter"。从源码结构看，这是一个由两百余个 crate 组成的大型 Cargo 工作区，根 Cargo.toml 的 members 列表覆盖了核心编辑器、GPU 渲染框架、AI/Agent 能力、协作后端等模块：

• 渲染与平台层：crates/gpui 及按平台拆分的 gpui_macos、gpui_linux、gpui_windows、gpui_web 等（工作区依赖中可见其使用 wgpu、metal 等图形栈）；
• 编辑核心：crates/editor、crates/languages、crates/language、crates/tree-sitter 相关语法高亮 crate；
• AI 与 Agent：crates/agent、crates/anthropic、crates/open_ai、crates/copilot 等；
• 协作与远程：crates/collab、crates/livekit_client、crates/remote_server；
• 入口二进制：crates/zed（主程序）与 crates/cli（命令行入口）。

工作区还固定了 edition = "2024"、publish = false，并通过 default-members = ["crates/zed"] 让裸跑 cargo run 直接构建编辑器主程序——这正是 README 中"装好依赖后 cargo run 即可运行"的底层原因。

安装 Zed

按 README 的 Installation 一节，Zed 支持 macOS、Linux、Windows 三个平台：可以直接从官方下载页获取安装包，也可以各平台对应的包管理器方式安装。README 同时明确指出 Web 版本尚未可用。普通用户走到这一步即可使用 Zed；下文面向希望修改、构建或贡献代码的开发者。

获取源码与 Rust 工具链

开发 Zed 的第一步是克隆仓库。工具链由仓库内的 rust-toolchain.toml 精确锁定，安装 rustup 后进入仓库目录会自动切换：

[toolchain]
channel = "1.97.1"
profile = "minimal"
components = [ "rustfmt", "clippy", "rust-analyzer", "rust-src" ]
targets = [
    "wasm32-wasip2",          # extensions
    "wasm32-unknown-unknown", # gpui on the web
    "x86_64-unknown-linux-musl", # remote server
]

从源码结构看，三个额外编译目标分别对应 Zed 的三项能力：WASI 目标用于编译扩展（extensions 以 WebAssembly 组件运行，依赖 Cargo.toml 中的 wasmtime 48 组件模型支持），wasm32-unknown-unknown 服务于 Web 端 gpui 实验，musl 目标则用于构建远程服务器二进制。

构建行为还受 .cargo/config.toml 全局约束，几个值得理解的配置：

[build]
# v0 mangling scheme provides more detailed backtraces around closures
rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]

[target.'cfg(target_os = "windows")']
rustflags = [
    "--cfg", "windows_slim_errors",   # 将 windows::core::Error 从 16 字节缩小到 4 字节
    "-C", "target-feature=+crt-static", # 修复在 Windows 上链接 livekit 的问题
]

[target.aarch64-unknown-linux-gnu]
rustflags = ["-C", "link-arg=-fuse-ld=lld"] # aarch64-linux 上需要用 lld 链接 libwebrtc.a

[env]
MACOSX_DEPLOYMENT_TARGET = "10.15.7"

这里还定义了若干常用 cargo 别名：cargo xtask 等价于 run --package xtask，cargo perf-test / cargo perf-compare 则以 release-fast profile 运行性能测试。

各平台构建依赖

macOS

依据 docs/src/development/macos.md，需要：

1. 安装 [rustup] 工具链（仓库会自动切到锁定版本）；

2. 安装 Xcode（App Store 或 Apple Developer 下载），安装后启动一次并安装 macOS 组件；

3. 安装并指向前者 Xcode 的命令行工具：

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

4. 安装 cmake（wasmtime 的 C API 依赖需要）：brew install cmake。

Linux

docs/src/development/linux.md 给出的官方做法是直接执行仓库自带的 script/linux 脚本。该脚本按发行版分支持了完整的依赖清单，以 Debian/Ubuntu 系为例需要：

gcc g++ make build-essential cmake clang lld llvm git curl jq gettext-base elfutils
libasound2-dev libfontconfig-dev libgit2-dev libglib2.0-dev libssl-dev libva-dev
libvulkan1 libwayland-dev libx11-xcb-dev libxkbcommon-x11-dev libzstd-dev
libsqlite3-dev musl-tools musl-dev pipewire xdg-desktop-portal

并会根据 /etc/os-release 的版本号追加 libstdc++-12-dev/libstdc++-14-dev；对较老的 Ubuntu 20.04 甚至会从 ubuntu-toolchain-r PPA 拉取 clang-18 与 libstdc++-11-dev（注释说明原因是编译 webrtc-sys 需要 C++20 支持）。脚本同样覆盖 Fedora/RHEL（dnf/yum，含 codeready-builder 仓库处理）、openSUSE（zypper）、Arch（pacman）、Void（xbps）、Gentoo（emerge）五套包管理器，安装完会顺带补装 rustup。

Windows

docs/src/development/windows.md 的要求最多：

• Visual Studio（含 MSVC C++ x64/x86 build tools 与 Spectre-mitigated libs 组件），或更精简的 Build Tools + "Desktop development with C++" 工作负载（后者需手动启动开发者 shell 才能被 rustup 识别）；
• Windows 10/11 SDK，至少需要 Windows 10 SDK version 2104；
• CMake（wasmtime 依赖所需，可通过 VS Installer 安装后手动把 bin 目录加入 PATH）。

文档还附上了完整的 VS Installer 组件清单 JSON（Microsoft.VisualStudio.Component.VC.Tools.x86.x64、Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake 等），并特别提醒：自 Visual Studio 2026 / MSVC 14.50 起 MSVC 版本与 VS 版本解耦，需要改选 MSVC Build Tools (Latest) 组件。

构建、运行与测试

三平台文档给出的核心命令完全一致，区别只在依赖准备：

# 调试构建并直接运行编辑器
cargo run

# 发布构建
cargo run --release

# 运行全工作区测试
cargo test --workspace

Linux 下还多两个实用入口：cargo run -p cli 以开发模式运行主界面 CLI crate；./script/install-linux 把本地构建安装到机器上。查看 script/install-linux 源码可知其流程：读取 crates/zed/RELEASE_CHANNEL 导出 ZED_CHANNEL，设置 ZED_UPDATE_EXPLANATION 提示（开发构建不走自动更新），调用 script/bundle-linux 以 release 模式构建 zed 与 cli 并打包为 target/release/zed-linux-${arch}.tar.gz，最后执行 script/install.sh 把二进制安装到 ~/.local/bin/zed、桌面文件到 ~/.local/share。

窗口系统方面，Linux 版 Zed 同时支持 X11 与 Wayland，默认运行时自动探测；在 Wayland 会话中可用 WAYLAND_DISPLAY='' 强制走 X11。文档同时为发行版打包者写了专门章节：Zed 有两个二进制——cli（放入 $PATH 并命名 zed）和 zed 本体（放到 cli 相对路径 ../../libexec/zed-editor 或 ../../lib/zed/zed-editor），.desktop 文件模板在 crates/zed/resources/zed.desktop.in（用 envsubst 填充值、重命名为 $APP_ID.desktop 并加执行权限）；还可用环境变量 ZED_UPDATE_EXPLANATION 关闭自动更新并给用户手动升级说明。

视觉回归测试（macOS 专属）

macOS 文档专门介绍了 Zed 的视觉回归测试：它截屏真实 Zed 窗口并与基线图对比，需要给终端授予 Screen Recording 权限。首次使用要先生成本地基线（基线存放于 crates/zed/test_fixtures/visual_tests/，为控制仓库体积被 gitignore）：

git checkout origin/main
UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
git checkout -

# 之后改动 UI 并确认预期变化后，重新更新基线
UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests

Windows 文档中注明该测试目前仅 macOS 可用。

性能剖析与诊断

两份平台文档把"高 CPU 场景如何取证"写得很具体，可直接当排障手册：

• Linux：ps -eo size,pid,comm | grep zed | sort | head -n 1 | cut -d ' ' -f 2 找到 zed-editor 的 PID，sudo perf record -g --call-graph dwarf -p <pid> 采样（--call-graph dwarf 走 .eh_frame 展开，适用于被 strip 的 release 二进制），配合 perf buildid-cache + perf inject 恢复符号，再用 flamegraph --perfdata 渲染火焰图；内存问题则推荐 heaptrack（cargo install cargo-heaptrack 后 cargo heaptrack -b zed，退出后用 heaptrack_interpret + heaptrack_gui 查看）。官方 release 的未 strip 符号文件由 script/bundle-linux 上传归档，可通过 build id 匹配下载。
• macOS：事发时 sample Zed 10 -f zed-sample.txt，并从命令面板的 About 复制精确版本/commit；事后由 script/bundle-mac 归档的 zed.dwarf 配合 atos -o zed.dwarf -l <load address> <address...> 解析符号。若要在本机带符号 profile，可把 zed.dwarf 转成 Zed.dSYM bundle 后再跑 sample。

常见构建故障速查

三份文档汇总的高频问题，按平台整理：

• 三平台通用：cargo 报依赖使用了 unstable features —— cargo clean && cargo build 通常可解决。
• macOS：xcrun: error: unable to find utility "metal" —— 重新 xcode-select --switch，macOS 26 上还需 xcodebuild -downloadComponent MetalToolchain；'dispatch/dispatch.h' file not found —— 除切换 Xcode 工具链外，还需 export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)" 后重建；测试报 Too many open files (os error 24) —— 改用 cargo install cargo-nextest 并 cargo nextest run --workspace --no-fail-fast。文档还有一个易踩的坑：用开发构建的 Zed 打开 Zed 自己的代码库会导致 rust-analyzer 继承 cargo run 导出的环境变量，反复使构建缓存失效，建议 cargo run ~/path/to/other/project 打开别的目录。
• Windows：设置 RUSTFLAGS 环境变量会覆盖 .cargo/config.toml 中必需的配置导致链接失败，需要额外 flag 时应写入 .cargo/config.toml 的 [build] 或 target 段，或在仓库父目录新建 .cargo/config.toml（CI 常用此法）；STATUS_ACCESS_VIOLATION 可能与 rust-lld 链接器有关，可换链接器；Invalid RC path selected 需手动设置 ZED_RC_TOOLKIT_PATH 指向 SDK 的 rc.exe 目录；path too long 需同时开启 git（core.longpaths）与 Windows 长路径支持；启动失败时查看 %LOCALAPPDATA%\Zed\logs\Zed.log，NoSupportedDeviceFound、GPU Crashed 等通常是 Vulkan 驱动问题。

开源许可与合规机制

README 的 Licensing 一节明确了 Zed 的许可策略：源码主要采用 GPL-3.0-or-later，带标注的部分为 Apache-2.0（对应仓库根目录的 LICENSE-GPL 与 LICENSE-APACHE）。第三方依赖的合规检查通过 cargo-about 自动化，且 CI 要求许可证信息正确。当 CI 因许可报错时，README 给出了三类处置路径，全部指向配置文件 script/licenses/zed-licenses.toml：

1. 自建 crate 报 no license specified：在该 crate 的 Cargo.toml 的 [package] 段加 publish = false（工作区默认 publish = false，Cargo.toml 的 [workspace.package] 已统一设置）；
2. 依赖报 failed to satisfy license requirements：先确认该依赖的许可证是否满足要求，确认后将 SPDX 标识符加入 accepted 数组——当前允许列表包括 Apache-2.0、MIT、MIT-0、MPL-2.0、BSD-2/3-Clause、ISC、CC0-1.0、OpenSSL、Zlib 等，文件注释明确写着 "AGPL should not be added to this list"；
3. cargo-about 找不到依赖的许可证：按 cargo-about 的配置格式在该文件末尾追加 clarify 段，指定 license 与 LICENSE 文件的 path + checksum。仓库中已有三个实例：procinfo（MIT）、webpki（ISC）、fuchsia-cprng（BSD-3-Clause）。

参与贡献与支持

README 的 Contributing 一节指向 CONTRIBUTING.md，其中详细说明了贡献方式。Zed 由 Zed Industries, Inc.（营利公司）开发，财务支持可通过 GitHub Sponsors 进行，赞助无附加权益。结合仓库内 .github CI、script/bundle-linux、script/bundle-mac 等打包脚本可以看出，本地开发构建与官方发布构建共用同一套脚本，这保证了"你能在本机构建"与"官方能发布"是同一条路径——这也是按本文流程走一遍之后，你能独立复现的完整链路。