第49章 在 Linux 上使用 Zed

标准安装

下载页上的安装脚本是安装 Zed 的最快方式：

curl -f https://zed.dev/install.sh | sh

我们还提供 Zed 的预览版构建，该版本比稳定版提前约一周更新。安装方式如下：

curl -f https://zed.dev/install.sh | ZED_CHANNEL=preview sh

通过脚本安装的 Zed 在以下系统上表现最佳：

• 具备 Vulkan 兼容的 GPU（例如运行 Linux 的 M 系列 MacBook）
• 拥有系统级 glibc
  • x86_64 (Intel/AMD)：glibc 版本 >= 2.31 (Ubuntu 20 及更新版本)
  • aarch64 (ARM)：glibc 版本 >= 2.35 (Ubuntu 22 及更新版本)

NixOS 默认没有系统级 glibc。如果你希望在 NixOS 上使用我们的构建版本，安装 glibc 兼容层（例如 nix-ld）可能会使其正常工作。

以下情况你需要从源码构建：

• 64 位 Intel 或 64 位 ARM 以外的架构（例如 32 位或 RISC-V 机器）
• 所有架构下的 Redhat Enterprise Linux 8.x、Rocky Linux 8、AlmaLinux 8 和 Amazon Linux 2
• aarch64 架构下的 Redhat Enterprise Linux 9.x、Rocky Linux 9.3、AlmaLinux 8 和 Amazon Linux 2023（x86_64 架构可以正常使用）

在 Linux 上安装 Zed 的其他方法

Zed 是开源的，你可以从源码安装。

通过包管理器安装

针对不同的 Linux 发行版和包管理器，有几个第三方的 Zed 软件包，有时命名为 zed-editor。可用性因发行版而异，但你可能可以使用其中一个软件包来安装 Zed：

• Arch: zed
• Arch (AUR): zed-git、zed-preview、zed-preview-bin
• Fedora/Ultramarine (Terra)：zed、zed-preview、zed-nightly
• Manjaro：zed
• Conda：zed
• Nix：zed-editor（unstable）
• Solus：zed
• Parabola：zed
• ALT Linux (Sisyphus)：zed
• AOSC OS：zed
• Flathub：dev.zed.Zed

各仓库中 Zed 软件包的最新列表可查看 Repology。

社区

安装第三方软件包时请注意，它可能不是最新版本，也可能与我们官方打包的 Zed 略有差异（常见的改动是把二进制文件重命名为 zedit 或 zeditor，以避免与其他软件包冲突）。

我们非常欢迎你帮助 Zed 触达更多用户。如果你的包管理器还没有 Zed，并且你希望解决这个问题，可以参考我们整理的打包指南。

本节中的软件包提供 Zed 的二进制安装，但并非相应发行版的官方软件包。它们由社区成员维护，安装时请多加留意。

手动下载

如果你愿意，也可以下载我们预构建的 .tar.gz 来安装 Zed。它与安装脚本使用的产物相同，但你可以按照下面的说明自定义安装位置：

下载 .tar.gz 文件：

• zed-linux-x86_64.tar.gz （预览版）
• zed-linux-aarch64.tar.gz （预览版）

确保 tar 包中的 zed 可执行文件已在系统路径中。最简单的方法是解包并创建符号链接：

mkdir -p ~/.local
# 将 zed 解压到 ~/.local/zed.app/
tar -xvf <path/to/download>.tar.gz -C ~/.local
# 将 zed 可执行文件链接到 ~/.local/bin（或 $PATH 中的其他目录）
ln -sf ~/.local/zed.app/bin/zed ~/.local/bin/zed

如果希望与兼容 XDG 的桌面环境集成，还需要安装 .desktop 文件：

install -D ~/.local/zed.app/share/applications/dev.zed.Zed.desktop -t ~/.local/share/applications
sed -i "s|Icon=zed|Icon=$HOME/.local/zed.app/share/icons/hicolor/512x512/apps/zed.png|g" ~/.local/share/applications/dev.zed.Zed.desktop
sed -i "s|Exec=zed|Exec=$HOME/.local/zed.app/bin/zed|g" ~/.local/share/applications/dev.zed.Zed.desktop

卸载 Zed

标准卸载

如果 Zed 是通过默认安装脚本安装的，可以通过在 zed Shell 命令后添加 --uninstall 参数来卸载：

zed --uninstall

注意，这将卸载符号链接所指向的 Zed 版本。如果您有多个并行安装（例如同时安装了 Stable 和 Preview 版），应使用下方本章节描述的绝对路径进行卸载。

如果没有报错，Shell 会询问您是否要保留偏好设置或将其删除。做出选择后，您将看到 Zed 成功卸载的消息。

如果在 PATH 中找不到 zed Shell 命令，可以尝试以下命令之一：

$HOME/.local/bin/zed --uninstall

或者你安装目录的绝对路径，例如

$HOME/.local/zed.app/bin/zed --uninstall

如果 $HOME/.local/bin/zed 和 $HOME/.local/zed.app/bin/zed 之间的符号链接未正确建立，或者由于并行安装了不同版本的 Zed 导致符号链接被覆盖，第一种方法可能会失败。但只要 Zed 安装在默认位置，第二种命令通常总能正常工作。

如果 Zed 安装在了其他位置（例如 zed-preview.app 版本），你必须调用该安装目录中存储的 zed 二进制文件，并以与上述命令相同的格式传入 --uninstall 标志。

包管理器

如果使用包管理器安装 Zed，请参考该包管理器的文档了解如何卸载软件包。

故障排查

Linux 运行在配置各异的多种系统上。我们主要在原生 Ubuntu 配置上测试 Zed，因为这是用户最常用的发行版。尽管如此，我们预计 Zed 能在多种机器上正常运行。

Zed 无法启动

如果你看到类似 “/lib64/libc.so.6: version 'GLIBC_2.29' not found” 的错误，说明你发行版的 glibc 版本过旧。你可以升级系统，或者从源码安装 Zed。

图形问题

Zed 无法打开窗口

Zed 需要 GPU 才能高效运行。底层我们使用Vulkan 与你的 GPU 通信。如果你遇到性能问题或 Zed 无法加载，可能是 Vulkan 出了问题。

如果你看到提示 Zed failed to open a window: NoSupportedDeviceFound，说明 Vulkan 找不到兼容的 GPU。你可以尝试运行 vkcube（在多数发行版中通常作为 vulkaninfo 或 vulkan-tools 包的一部分提供）来排查问题来源：

vkcube

注意：可以运行 vkcube -m [x11|wayland]，分别测试 X11 和 wayland 模式。部分版本的 vkcube 需要用 vkcube 运行 X11，用 vkcube-wayland 运行 wayland。

运行后应该会输出一行描述当前显卡环境的信息，并显示一个旋转的立方体。如果无法运行，通常安装支持 Vulkan 的 GPU 驱动即可解决，但个别情况下设备还不支持 Vulkan。

想确认 Zed 当前使用的是哪块显卡，可以在 Zed 日志（~/.local/share/zed/logs/Zed.log）中查找 Using GPU: ...。

如果看到 ERROR_INITIALIZATION_FAILED、GPU Crashed 或 ERROR_SURFACE_LOST_KHR 这类错误，可以尝试更换 GPU 驱动，或切换到另一块 GPU 上运行（参见 #14225）。

在某些系统上，可以通过 /etc/prime-discrete 文件配合 PRIME 强制使用独立 GPU。视具体配置而定，你可能需要把这个文件的内容改为 "on"（强制使用独立显卡）或 "off"（强制使用集成显卡）。

在其他系统上，可以在启动 Zed 时设置环境变量 DRI_PRIME=1 来强制使用独立 GPU。

如果用的是 AMD GPU，可能会遇到 'Broken Pipe' 错误。可以尝试改用 RADV 或 Mesa 驱动（参见 #13880）。

如果你使用的是 AMD 默认的开源驱动 amdvlk，可能会发现 Zed 始终无法启动。这是部分用户遇到的已知问题，例如在 Omarchy 上（参见 issue #28851）。解决办法是换用其他驱动，建议卸载 amdvlk 和 lib32-amdvlk，改用 vulkan-radeon（参见 issue #14141）。

更多信息可参考 Arch 的 Vulkan 指南，其中的步骤同样适用于大多数发行版。

强制 Zed 使用指定 GPU

有几种方法可以让 Zed 强制使用指定的 GPU：

方案 A

可以使用环境变量 ZED_DEVICE_ID={device_id} 来指定目标 GPU 的设备 ID。

运行 lspci -nn | grep VGA 即可获取 GPU 的设备 ID，输出会逐行列出每块 GPU，例如：

08:00.0 VGA compatible controller [0300]: NVIDIA Corporation GA104 [GeForce RTX 3070] [10de:2484] (rev a1)

其中的设备 ID 是 2484。该值为十六进制，若要强制 Zed 使用这块 GPU，应这样设置环境变量：

ZED_DEVICE_ID=0x2484 zed

如果选择在 .bashrc 或类似文件中全局定义，记得 export 该变量。

方案 B

如果使用 Mesa，可运行 MESA_VK_DEVICE_SELECT=list zed --foreground 列出可用 GPU，再 export MESA_VK_DEVICE_SELECT=xxxx:yyyy 以选择特定设备。此外，通过额外 export WAYLAND_DISPLAY="" 可以回退到 xwayland。

方案 C

使用 vkdevicechooser。

报告图形问题

如果 Vulkan 配置正确但 Zed 仍无法正常工作，请提交 issue，并尽可能提供详细信息。

在 GitHub 报告因图形初始化错误导致 Zed 无法启动的问题时，可能无法像我们在 issue 模板中指示的那样执行 {#action zed::CopySystemSpecsIntoClipboard} 命令。我们提供了另一种专门针对此场景收集系统信息的方法。

向 Zed 传入 --system-specs 参数，例如：

zed --system-specs

它会在终端打印系统规格，格式如下。强烈建议将该输出原样复制到 GitHub issue 中，因为它使用 markdown 格式以确保可读性。

另外，报告此类问题时提供 Zed 日志内容也非常有帮助。日志通常位于 ~/.local/share/zed/logs/Zed.log。生成有效日志文件的推荐步骤如下：

truncate -s 0 ~/.local/share/zed/logs/Zed.log # 清空日志文件
ZED_LOG=wgpu=info zed .
cat ~/.local/share/zed/logs/Zed.log
# 复制输出内容

或者，如果你已经配置了 Zed CLI，可以执行以下命令：

ZED_LOG=wgpu=info /path/to/zed/cli --foreground .
# 复制输出内容

将日志粘贴到 GitHub issue 时，强烈建议使用以下模板：

注意：模板中的空白字符很重要，如果未保留，会导致格式错误。

<details><summary>Zed Log</summary>

```
{zed log contents}
```

</details>

这样日志默认会是折叠状态，便于阅读 issue 内容。

无法打开文件

点击链接无效

这些功能由 XDG desktop portals 提供，具体包括：

• org.freedesktop.portal.FileChooser
• org.freedesktop.portal.OpenURI

某些窗口管理器（如 Hyprland）默认不提供文件选择器。可参考此列表寻找替代方案。

Zed 未记住我的 API 密钥

Zed 未记住我的登录状态

该功能同样依赖 XDG desktop portals，具体包括：

• org.freedesktop.portal.Secret 或
• org.freedesktop.Secrets

Zed 需要一个安全的地方来存储机密信息，例如 Zed 登录 Cookie 或 OpenAI API 密钥，我们使用系统提供的密钥链来实现。提供此功能的包示例包括 gnome-keyring、KWallet 和 keepassxc 等。

无法启动 inotify

Zed 依赖 inotify 来监视文件系统变更。如果无法启动 inotify，Zed 将无法可靠运行。

如果看到“打开文件过多”的错误，请先尝试 sysctl fs.inotify。

• 你应该看到 max_user_instances 为 128 或更高（可通过 sudo sysctl fs.inotify.max_user_instances=1024 修改限制）。Zed 仅需 1 个 inotify 实例。
• 你应该能看到 max_user_watches 的值为 8000 或更高（可以通过 sudo sysctl fs.inotify.max_user_watches=64000 修改该限制）。Zed 需要为打开项目中的每个目录分配一个 watch，每个 git 仓库一个，另外设置、主题、键位、扩展等还需要占用一些。

也可能是文件描述符不够用了。你可以用 ulimit 查看限制，并通过编辑 /etc/security/limits.conf 来调整。

没有声音或输出设备不对

如果你在 Zed 里听不到声音，或者音频被输出到了错误的设备，可能是音频系统不匹配导致的。Zed 依赖 ALSA，而你的系统可能在用 PipeWire 或 PulseAudio。要解决这个问题，需要配置 ALSA，让它通过 PipeWire/PulseAudio 路由音频。

如果你的系统使用 PipeWire：

1. 安装 PipeWire 的 ALSA 插件

   在 Debian 系发行版上运行：

   sudo apt install pipewire-alsa
   

2. 配置 ALSA 使用 PipeWire

   将以下配置添加到 ALSA 设置文件中，可以使用 ~/.asoundrc（用户级别）或 /etc/asound.conf（系统级别）：

   pcm.!default {
       type pipewire
   }
   
   ctl.!default {
       type pipewire
   }
   

3. 重启系统

强制指定 X11 缩放系数

在 X11 系统上，Zed 会自动检测高 DPI 显示器合适的缩放系数，检测按以下优先级进行：

1. GPUI_X11_SCALE_FACTOR 环境变量（如果已设置）
2. X resources 数据库（xrdb）中的 Xft.dpi
3. 通过 RandR 根据显示器分辨率和物理尺寸自动检测

如果你想在 Zed 自动检测的基础上自定义缩放系数，有以下几种方式：

查看当前的缩放系数

你可以检查是否设置了 Xft.dpi：

xrdb -query | grep Xft.dpi

如果这条命令没有输出，说明 Zed 正在通过 RandR（X11 的显示器管理扩展）根据显示器报告的分辨率和物理尺寸自动计算缩放系数。

方案一：设置 Xft.dpi（X Resources 数据库）

Xft.dpi 是 X11 的标准设置，许多应用程序都依靠它来统一字体和 UI 缩放。配置该项可确保 Zed 与其他尊重此设置的 X11 应用保持相同的缩放比例。

编辑或创建 ~/.Xresources 文件：

vim ~/.Xresources

加入指定 DPI 的配置行：

Xft.dpi: 96

常见 DPI 取值：

• 96：标准 1 倍缩放
• 144：1.5 倍缩放
• 192：2 倍缩放
• 288：3 倍缩放

加载配置：

xrdb -merge ~/.Xresources

重启 Zed 以生效。

方案 2：使用 GPUI_X11_SCALE_FACTOR 环境变量

这是 Zed 专属的环境变量，用于直接设定缩放因子，跳过所有自动检测逻辑。

GPUI_X11_SCALE_FACTOR=1.5 zed

支持小数取值（例如 1.25、1.5、2.0）。若需强制使用基于 RandR 的检测，即使已设置 Xft.dpi，也可将 GPUI_X11_SCALE_FACTOR 设为 randr。

若要永久生效，请将该项添加到 Shell 配置文件或桌面启动项中。

方案 3：调整系统级 RandR DPI

此操作会修改整个 X11 会话报告的 DPI，进而影响所有使用 RandR 计算缩放的应用程序。

在 .xprofile 或 .xinitrc 中添加以下命令：

xrandr --dpi 192

将 192 替换为所需的 DPI 值。该设置对系统全局有效；当未设置 Xft.dpi 时，Zed 的自动 RandR 检测将采用此值。

字体渲染参数

在 Linux 下，Zed 通过读取 ZED_FONTS_GAMMA 和 ZED_FONTS_GRAYSCALE_ENHANCED_CONTRAST 环境变量来确定字体渲染参数。

ZED_FONTS_GAMMA 对应 getgamma 的取值。 允许范围为 [1.0, 2.2]，超出范围的数值会被截断。 默认值：1.8

ZED_FONTS_GRAYSCALE_ENHANCED_CONTRAST 对应 getgrayscaleenhancedcontrast 的值。 允许范围：[0.0, +∞)，超出范围的值会被截断。 默认值：1.0