Zed for Linux：从源码构建、安装打包到内存剖析与性能调优完整指南

导读

本文是 Zed 编辑器在 Linux 平台上的开发与交付实践指南，覆盖依赖安装、Debug/Release 构建、本地安装、面向发行版维护者的打包规范、Flatpak 打包，以及 heaptrack 内存剖析与 perf 火焰图性能录制等完整流程。读完本文，你将掌握从零把 Zed 跑起来、并以源码级证据理解其二进制布局与发布渠道机制，可用于日常开发调试、自用构建和发行版维护。

本文内容以仓库内文档 docs/src/development/linux.md 为主线，代码层面的事实均可在仓库对应脚本与源码中验证。

仓库准备

首先获取 Zed 源码：

git clone https://gitcode.com/GitHub_Trending/ze/zed
cd zed

Zed 是使用 Rust 编写的高性能、多人协作代码编辑器。整个构建流程围绕两个核心产物展开：编辑器本体（crates/zed）与命令行入口（crates/cli）。仓库根目录的 Cargo.toml、rust-toolchain.toml 与 script/ 目录内的各类 shell 脚本共同构成了完整的 Linux 构建工具链。

安装依赖

构建 Zed 需要两步依赖：

1. Rust 工具链（rustup 是推荐方式）；
2. 系统级库（图形、音频、加密、数据库、编译器等）。

一键脚本 script/linux

仓库提供了全自动依赖安装脚本 script/linux。它会自动识别当前发行版，并为该发行版挑选合适的包管理器与包清单：

script/linux

脚本执行完成后会自动补装 rustup（若系统中尚未检测到 rustup）。需要说明的是，脚本通过 sudo/doas 提权，且会修改系统软件源（如为老旧 Ubuntu 20.04 添加 ubuntu-toolchain-r PPA），因此在执行前请确认你了解其影响。

各发行版依赖一览

从 script/linux 源码可以看出其支持以下发行版家族：

发行版家族	检测命令	关键处理逻辑
Ubuntu / Debian / Mint / Kali / Pop!_OS / Raspbian	apt-get	依据 /etc/os-release 中的 PRETTY_NAME 匹配版本，为 Ubuntu 20.04 添加 clang-18 与 libstdc++-11-dev（PPA 源），22.04/24.04 等添加对应 libstdc++ 版本
Fedora / CentOS / RHEL / Alma / Amazon 2023 / Oracle	dnf / yum	Fedora 需额外安装 perl-FindBin 等 perl 模块；RHEL 系需启用 powertools/crb/ol*_codeready_builder 仓库，RHEL 8 系用 gcc-c++
openSUSE	zypper	包含 xcb-util-devel、libvulkan1 等包
Arch / Manjaro	pacman	pacman -Syu --needed --noconfirm
Void	xbps-install	包含 elfutils-devel 等包
Gentoo	emerge	使用 Portage 包名命名（如 dev-build/cmake）

如果你不希望使用脚本，可以阅读 script/linux 中对应分支的 deps 数组自行安装。

这些依赖包按功能可归类为：

• 图形与窗口系统：libwayland-dev、libx11-xcb-dev、libxkbcommon-x11-dev（X11/Wayland 支持）；
• GPU 渲染：libvulkan1/vulkan-loader、libva-dev（Zed 基于 GPUI 使用 GPU 渲染）；
• 音频：libasound2-dev/alsa-lib、pipewire；
• 编译工具链：clang、lld、llvm、cmake、gcc/g++（用于编译依赖如 webrtc-sys）；
• 运行时/加密/数据库：libssl-dev/openssl、libgit2-dev、libsqlite3-dev、libzstd-dev；
• 桌面集成：xdg-desktop-portal、gettext-base（提供 envsubst，打包 .desktop 文件时需要）、elfutils、jq；
• musl 工具链：musl-tools/musl-gcc/musl-dev（用于构建静态链接的 remote_server）。

从源码构建

依赖就绪后，即可使用 Cargo 构建。Zed 的 debug 构建体积与编译时间更友好，适合日常开发：

cargo run

运行工作区全部测试：

cargo test --workspace

在 release 模式下，面向终端用户的主界面入口是 cli crate。开发期直接运行它即可验证 CLI 行为：

cargo run -p cli

cli 是一个独立二进制，负责唤起 Zed 主程序并建立 IPC 通信，因此它不会把你拖进完整 GUI 的编译与运行链路。

安装一个本地开发构建

想把自编译的版本装到机器上，只需一条命令：

./script/install-linux

执行过程可以拆解为两步，均可在仓库脚本中验证：

1. script/install-linux 首先读取 crates/zed/RELEASE_CHANNEL（当前仓库内容为 dev）导出 ZED_CHANNEL，同时设置 ZED_UPDATE_EXPLANATION 为提示文本，随后调用 script/bundle-linux 以 release 模式产出 zed-linux-$(uname -m).tar.gz 压缩包；
2. 压缩包交由 script/install.sh 解压到 ~/.local/，最终效果是：
   • CLI 入口软链接到 ~/.local/bin/zed（链接目标为 ~/.local/zed.app/bin/zed，脚本对 0.139.x 之前版本做了 bin/cli 兼容回退）；
   • .desktop 文件被安装到 ~/.local/share/applications，其中 Icon 与 Exec 路径会被 sed 改写为绝对路径；
   • 若 ~/.local/bin 不在 PATH 中，脚本会按你当前 shell（zsh/fish/bash）给出对应的 PATH 配置命令。

Wayland 与 X11

Zed 同时支持 X11 与 Wayland，默认在运行时探测可用的显示协议并自动选择。如果你正运行在 Wayland 会话中、却想强制以 X11 模式启动，可通过置空 WAYLAND_DISPLAY 实现：

WAYLAND_DISPLAY='' zed

对应能力由 gpui_linux 与 gpui_wgpu 等 crate 提供，前者负责窗口系统接入，后者负责基于 Vulkan/WGPU 的渲染后端。

发行版打包注意事项

本节面向需要把 Zed 打包进系统仓库的分发维护者。

二进制布局

Zed 交付时包含两个主要二进制，位置关系必须严格满足约定：

• 构建 crates/cli，将其二进制命名为 zed 并放进 $PATH；
• 构建 crates/zed，并将其放置于 $PATH/to/cli/../../libexec/zed-editor。例如 CLI 位于 ~/.local/bin/zed，则主程序放 ~/.local/libexec/zed-editor；
• 由于部分发行版（尤其是 Arch）不鼓励使用 libexec，也可将主程序放在 $PATH/to/cli/../../lib/zed/zed-editor，例如 ~/.local/lib/zed/zed-editor。

这一约定与 script/bundle-linux 中的打包逻辑一致：该脚本把 zed 复制为 libexec/zed-editor、把 cli 复制为 bin/zed，并通过 -Wl,--disable-new-dtags,-rpath,$ORIGIN/../lib 让主程序从同目录的 lib/ 加载随包动态库。

.desktop 文件

打包时可参考 crates/zed/resources/zed.desktop.in 模板，用 envsubst 填充占位变量（$APP_NAME、$APP_CLI、$APP_ICON、$APP_ARGS、$DO_STARTUP_NOTIFY）。该文件需重命名为 $APP_ID.desktop 以符合 FreeDesktop 规范，并赋予可执行权限：

chmod 755 dev.zed.Zed.desktop

APP_ID 随发布渠道变化：stable 为 dev.zed.Zed，nightly/preview/dev 分别为 dev.zed.Zed-Nightly、dev.zed.Zed-Preview、dev.zed.Zed-Dev（见 script/bundle-linux）。模板中还保留了 [Desktop Action NewWorkspace]（执行 zed --new）以及 MimeType 注释，提示如需“以 Zed 打开文件夹”需自行加入 inode/directory。

运行时系统库

打包者必须确保目标系统具备 Zed 所需的动态库。可在构建产物上直接检查以获取当前清单：

ldd target/release/zed

官方打包脚本 script/bundle-linux 中有一段 find_libs() 逻辑：它会把非 glibc 基础库（排除 libc/libm 等以及 glib/gobject 等 GLib 家族）复制进 lib/ 目录随包分发，其中显式捆绑 libstdc++，以便在较老系统（缺少新版 GLIBCXX 符号）上运行。注释还提醒：绝不捆绑 GLib 家族及其私有依赖，否则宿主 dlopen 的库会与随包旧版本发生符号冲突。

关闭自动更新

Zed 内置自动更新机制。打包者可用环境变量 ZED_UPDATE_EXPLANATION 关闭自动更新，并在用户手动尝试更新时显示自定义指引。例如：

ZED_UPDATE_EXPLANATION="Please use flatpak to update zed." zed

设置 RELEASE_CHANNEL

务必更新 crates/zed/RELEASE_CHANNEL 文件内容为 nightly、preview 或 stable 三者之一，且结尾不能有换行符。这一内容在编译期被写入二进制（见下文“发布渠道机制”），它决定 Zed 是否启用凭据管理器来记忆用户登录态。

发布渠道机制：RELEASE_CHANNEL 如何生效

从 crates/release_channel/src/lib.rs 源码可以看出：正常编译时通过 include_str!("../../zed/RELEASE_CHANNEL") 把该文件内容在编译期固化进程序；在 debug 断言开启的构建中还可通过 ZED_RELEASE_CHANNEL 环境变量临时覆盖。非法渠道值会在 RELEASE_CHANNEL 的 LazyLock 初始化阶段直接 panic，因此打包前务必校验文件内容。而 crates/zed/build.rs 与 script/bundle-linux 读取的渠道值还会影响归档命名、.desktop 的 APP_ID 与 APP_NAME。

其他注意事项

官方文档同样提示以下事实与权衡：

• Zed 迭代很快，维护者通常每周发布 2~3 个构建来修复问题并携带较大改动；
• Linux 生态中可能已存在同名 zed 二进制（如 OpenZFS 的 zed 守护进程、Brim Data 的 zed 查询命令）。若需改名，官方建议使用 zedit、zeditor 或 zed-cli；
• Zed 会自动安装常见开发者工具（机制类似 rustup/rbenv/pyenv）；
• 用户可以本地或从扩展市场安装扩展，扩展可能附带语言服务器等额外工具；
• Zed 默认会连接若干在线服务（AI、遥测、协作）。AI 与遥测可由用户在设置中关闭，也可通过修改 assets/settings/default.json 默认设置文件实现；
• 正因上述原因，Zed 目前与沙箱环境兼容性有限。

Flatpak 打包

注意：Zed 当前的 Flatpak 集成会在启动时退出沙箱。依赖 Flatpak 沙箱隔离的工作流可能不符合预期。

本地构建并安装 Flatpak 包：

1. 按官方指引为你的发行版安装 Flatpak；
2. 运行 script/flatpak/deps 安装依赖：它会向用户级仓库添加 Flathub，并安装 org.freedesktop.Platform、org.freedesktop.Sdk 及其 rust-stable 扩展（均为 23.08 版本，架构取自 arch）；
3. 运行 script/flatpak/bundle-flatpak。该脚本先以 --flatpak 参数调用 script/bundle-linux（会导出 ZED_BUNDLE_TYPE=flatpak），再依据 crates/zed/RELEASE_CHANNEL 的值选择对应 APP_ID（dev/nightly/preview/stable 分别为 dev.zed.ZedDev、dev.zed.ZedNightly、dev.zed.ZedPreview、dev.zed.Zed），用 envsubst 展开 crates/zed/resources/flatpak/manifest-template.json，随后通过 flatpak-builder --user --install 安装、flatpak build-bundle 生成安装包；
4. 安装完成后，安装包位于 target/release/{app-id}.flatpak。

内存剖析：heaptrack

当需要排查 Zed 的内存泄漏问题时，heaptrack 是实用工具。安装方式：

sudo apt install heaptrack heaptrack-gui
cargo install cargo-heaptrack

随后让 Zed 在剖析器下构建并运行：

cargo heaptrack -b zed

退出该 Zed 实例后，终端输出会附带一条命令：使用 heaptrack_interpret 把 *.raw.zst 剖析结果转换成 *.zst 文件，再交给 heaptrack_gui 可视化查看。

性能录制：perf 火焰图

当 Zed 占用大量 CPU 时可使用本节方法抓取带符号解析的火焰图（该法对进程卡死场景无效）。

事发时

1. 找到进程 PID：

   ps -eo size,pid,comm | grep zed | sort | head -n 1 | cut -d ' ' -f 2
   

   或在 htop/btop/top 中定位占用 RAM 最高的 zed-editor 进程；

2. 安装 perf（Ubuntu 系）：

   sudo apt install linux-tools
   

3. 录制性能数据：

   sudo perf record -g --call-graph dwarf -p <pid>
   

   等待数秒采集后按 Ctrl+C，当前目录会生成 perf.data。--call-graph dwarf 会为每个采样函数记录调用者，并通过剥离后 release 二进制中保留的 .eh_frame 数据完成栈回溯；没有 frame pointer 时仅用 -g 无效；

4. 让输出文件归属当前用户：

   sudo chown $USER:$USER perf.data
   

5. 记录构建信息：再次启动 Zed，在命令面板中执行 zed::About（对应动作 {#action zed::About}），得到精确 commit。

随后可将 perf.data 连同该 commit 一并交给 Zed 团队。

事后分析

这一步通常由 Zed 团队完成。官方发布的 Linux 二进制是剥离过的，但每个 release 的未剥离二进制都已由 script/bundle-linux 上传至 Sentry（可从 Sentry 项目的 Debug Files 页按 release 版本或二进制 build id 下载）。剥离操作会保留 build id，因此下载的二进制能与用户的 perf.data 精确匹配，之后继续执行 perf buildid-cache 步骤即可。

另一种方式是自行重建带符号的二进制：

1. 切到上一步找到的 commit，修改 Cargo.toml，应用如下 diff 后执行 release 构建：

   [profile.release]
   -debug = "limited"
   +debug = "full"
   

2. 把符号加入 perf 数据库：

   perf buildid-cache -v -a <path to release zed binary>
   

3. 从数据库解析符号并生成新数据文件：

   perf inject -i perf.data -o perf_with_symbols.data
   

4. 安装火焰图渲染工具：

   cargo install cargo-flamegraph
   

5. 渲染火焰图：

   flamegraph --perfdata perf_with_symbols.data
   

疑难排查

Cargo 报错提示依赖使用了不稳定的特性

若出现此类编译错误，通常是增量构建缓存损坏所致。可先执行 cargo clean 清理后重新构建：

cargo clean && cargo build

延伸阅读

• 依赖安装脚本：script/linux
• 本地安装封装：script/install-linux 与 script/install.sh
• 发行版打包参考脚本：script/bundle-linux
• .desktop 模板：crates/zed/resources/zed.desktop.in
• 发布渠道说明与 Flatpak 脚本：crates/zed/RELEASE_CHANNEL、script/flatpak/deps、script/flatpak/bundle-flatpak
• 渠道解析实现：crates/release_channel/src/lib.rs
• CLI 入口实现：crates/cli/src/main.rs