为 macOS 构建 Zed

仓库

克隆 Zed 仓库。

依赖项

确保安装后启动 Xcode，并安装 macOS 组件（这是默认选项）。

  • 安装 Xcode 命令行工具

    xcode-select --install

  • 确保 Xcode 命令行工具正在使用您新安装的 Xcode 副本

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

  • 安装 cmake（一个依赖项所需）

    brew install cmake

后端依赖项（可选）

如果您希望使用本地协作服务器开发 Zed 协作功能，请参阅：本地协作 文档。

从源代码构建 Zed

安装依赖项后，您可以使用 Cargo 构建 Zed。

用于调试构建

cargo run

用于发布构建

cargo run --release

并运行测试

cargo test --workspace

故障排除

编译 Metal 着色器错误

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

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)（打开文件过多 (操作系统错误 24)）

此错误似乎是由操作系统资源限制引起的。安装并使用 cargo-nextest 运行测试应该可以解决此问题。

  • cargo install cargo-nextest --locked
  • cargo nextest run --workspace --no-fail-fast

提示与技巧

避免持续重建

如果您发现 Zed 持续重建根 crates，可能是因为您将开发中的 Zed 指向了代码库本身。

这会导致问题，因为 cargo run 会导出大量环境变量，这些变量会被在 Zed 开发构建中运行的 rust-analyzer 捕获。这些环境变量又会被传递给 cargo check，从而使我们依赖的一些 crates 的构建缓存失效。

您可以使用 cargo run ~/path/to/other/project 轻松避免在签出的 Zed 代码库上运行构建的二进制文件，以确保您不会遇到此问题。

加快验证速度

如果您经常构建 Zed，您可能会发现 macOS 持续验证新的构建，这可能会使您的迭代周期增加几秒钟。

要解决此问题，您可以

  • 运行 sudo spctl developer-mode enable-terminal 以在“系统设置”中启用“开发者工具”面板。
  • 在“系统设置”中，搜索“开发者工具”，并将您的终端（例如 iTerm 或 Ghostty）添加到“允许应用程序使用开发者工具”下的列表中。
  • 重启您的终端。

感谢 nextest 开发者发布了此信息。