第144章 在 macOS 上从源码构建 Zed 编辑器
代码仓库
克隆 Zed 代码仓库。
依赖项
-
安装 rustup
-
从 macOS App Store 或 Apple Developer 网站安装 Xcode。从 Apple Developer 网站下载需要开发者账户。
安装完成后启动 Xcode，并安装 macOS 组件（默认选项）。
- 安装 Xcode 命令行工具
sh
xcode-select --install
- 确保 Xcode 命令行工具指向新安装的 Xcode 副本：
sh
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
- 安装
cmake（某个依赖项 需要）
sh
brew install cmake
从源码构建 Zed
安装好依赖项后，可使用 Cargo 构建 Zed。
进行调试构建：
cargo run
进行发布构建：
cargo run --release
运行测试：
cargo test --workspace
视觉回归测试
Zed 包含视觉回归测试，用于截取真实 Zed 窗口的屏幕截图，并与基准图像进行比对。这些测试需要在 macOS 上授予屏幕录制权限。
前置条件
必须授予终端屏幕录制权限：
- 运行一次视觉测试执行器 - macOS 会弹出权限请求
- 或手动操作：系统设置 > 隐私与安全性 > 屏幕录制
- 启用你的终端应用（例如 Terminal.app、iTerm2、Ghostty）
- 授予权限后重启终端
运行视觉测试
cargo run -p zed --bin zed_visual_test_runner --features visual-tests
基准图像
基线图片存放在 crates/zed/test_fixtures/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 的基线。
更新基线
当 UI 改动是有意为之时，在改动之后更新基线图片：
UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
注意：未来基线可能会存放在外部。目前它们仅保存在本地，以保持 git 仓库轻量。
对已发布构建进行采样
如何从已发布（非 dev）的 Zed 实例获取符号化后的 CPU profile。当 Zed 占用大量 CPU 时可以使用这个方法。
macOS 的发布二进制文件剥离了本地符号，因此 sample 和 Instruments 对大多数帧只会显示原始地址。每个版本的调试符号都有归档：script/bundle-mac 会在剥离符号前把 zed.dwarf 上传到 Sentry。
问题发生时
- 运行
sample Zed 10 -f zed-sample.txt（如果使用 Preview 或 Nightly，请相应调整进程名）。 - 获取确切的构建版本：在命令面板中输入 {#action zed::About}，复制版本号和 commit。
可以把 zed-sample.txt 连同确切的版本信息一起发给 Zed 团队。
事后
这一步可以由 Zed 团队成员完成。
- 在采样输出底部的
Binary Images部分找到二进制文件的 UUID。 - 用该 UUID 在 Sentry 项目的 Debug Files 页面搜索并下载对应的
zed.dwarf。 - 解析地址：
atos -o zed.dwarf -l <load address> <address...>采样输出中每个未解析的帧都会打印其load address和绝对地址。
若要在本机对发布版进行完整带符号的性能剖析，请下载对应的 zed.dwarf，将其转换为 Spotlight 可索引的 .dSYM 包，然后重新运行 sample：
mkdir -p Zed.dSYM/Contents/Resources/DWARF
cp zed.dwarf Zed.dSYM/Contents/Resources/DWARF/zed
这样堆栈帧会自动解析，包含文件和行号信息。
故障排除
Metal shader 编译错误
error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
xcrun: error: unable to find utility "metal", not a developer tool or in PATH
尝试运行 sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
如果使用 macOS 26，请运行 xcodebuild -downloadComponent MetalToolchain。
若该命令失败，请执行 xcodebuild -runFirstLaunch 后再次尝试下载工具链。
Cargo 报错称依赖项使用了不稳定特性
尝试运行 cargo clean 和 cargo build。
错误：找不到 'dispatch/dispatch.h' 文件
如果遇到类似以下错误：
src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
Caused by:
process didn't exit successfully
--- stdout
cargo:rustc-link-lib=framework=System
cargo:rerun-if-changed=src/platform/mac/dispatch.h
cargo:rerun-if-env-changed=TARGET
cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
该文件属于 Xcode。请确保已安装 Xcode 命令行工具，并且路径设置正确：
xcode-select --install
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
此外，设置 BINDGEN_EXTRA_CLANG_ARGS 环境变量：
export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
然后清理并重新构建项目：
cargo clean
cargo run
测试因 Too many open files (os error 24) 而失败
此错误可能是由操作系统资源限制引起的。安装并使用 cargo-nextest 运行测试可解决该问题。
cargo install cargo-nextest --lockedcargo nextest run --workspace --no-fail-fast
技巧与提示
避免频繁重新构建
如果 Zed 持续重新构建根 crate，可能是你在开发版本中打开了 Zed 自身的代码库。
这会导致问题，因为 cargo run 导出一系列环境变量，这些变量会被运行在 Zed 开发版本中的 rust-analyzer 捕获。这些环境变量随后传递给 cargo check，导致部分依赖 crate 的构建缓存失效。
为避免此问题，请针对其他项目运行已构建的二进制文件，例如 cargo run ~/path/to/other/project。
加速验证过程
如果你频繁构建 Zed，macOS 可能会不断对新构建进行验证，从而增加每次迭代的几秒钟耗时。
要修复此问题，可以执行以下操作：
- 运行
sudo spctl developer-mode enable-terminal以在系统设置中启用“开发者工具”面板。 - 在系统设置中搜索“Developer Tools”，并将你的终端（如 iTerm 或 Ghostty）添加到“允许应用使用开发者工具”列表中。
- 重启终端。
感谢 nextest 开发团队发布了这项资源。
