奇链 奇链
← 教程库 / Zed 官方手册
入门 Zed Industries 2026-09-13 18:46:37 · 1 阅读

第103章 开发工具 Zed 入门指南

Zed 是一款内置协作与 AI 工具的开源代码编辑器。

本指南涵盖核心命令、环境配置及基础导航操作。

快速入门

欢迎页

在未打开任何文件夹时，主编辑区会显示 Zed 的欢迎页。该页面提供快捷操作，可打开文件夹、克隆仓库或查看文档。一旦打开文件夹或文件，欢迎页即会消失。若将编辑器分割为多个窗格，欢迎页仅在中间窗格为空时显示，其他窗格则显示标准的空白状态。

如需重新打开欢迎页，可关闭中间窗格中的所有内容，或在命令面板中搜索“Welcome”。

1. 打开项目

从命令行打开文件夹：

zed ~/projects/my-app

或在 Zed 内部使用 Cmd+O（macOS）/ Ctrl+O（Linux/Windows）打开文件夹。

默认情况下，新项目会在当前窗口的线程侧边栏中打开。若希望在新窗口中打开，可使用 zed -n ~/projects/my-app，或在从“最近打开”中选择时按 Cmd+Enter。更多详情参见 Windows & Projects。

2. 掌握核心命令

操作macOSLinux/Windows
命令面板Cmd+Shift+PCtrl+Shift+P
跳转到文件Cmd+PCtrl+P
跳转到符号Cmd+Shift+OCtrl+Shift+O
项目内查找Cmd+Shift+FCtrl+Shift+F
切换终端Ctrl+`Ctrl+`
打开设置Cmd+,Ctrl+,

命令面板（Cmd+Shift+P）是执行 Zed 内所有操作的入口。若忘记快捷键，可直接在此处搜索。

面板布局

如果您希望 Agent Panel 和 Threads Sidebar 并排显示在左侧，请在标题栏的用户菜单中选择 Panel Layout > Agentic（或执行 workspace: use agentic layout 操作）。若要恢复以编辑器为中心的布局，请选择 Panel Layout > Classic（或执行 workspace: use classic layout）。

3. 配置编辑器

使用 Cmd+,（macOS）或 Ctrl+,（Linux/Windows）打开设置编辑器。您可以直接搜索并修改任意配置项。

常见的初期调整包括：

  • 主题：按 Cmd+K Cmd+T（macOS）或 Ctrl+K Ctrl+T（Linux/Windows）打开主题选择器
  • 字体：在设置中搜索 buffer_font_family
  • 保存时格式化：搜索 format_on_save 并设为 on

4. 配置语言支持

Zed 内置支持多种语言。对于其他语言，请安装相应的扩展插件：

  1. 使用 Cmd+Shift+X（macOS）或 Ctrl+Shift+X（Linux/Windows）打开扩展管理界面
  2. 搜索您所需的语言
  3. 点击安装

请参阅 语言 文档，获取特定语言的配置指南。

5. 体验 AI 功能

Zed 内置了 AI 辅助功能。使用 Cmd+Shift+A（macOS）或 Ctrl+Shift+A（Linux/Windows）打开 Agent Panel 开始对话，或使用 Cmd+Enter（macOS）/ Ctrl+Enter（Linux/Windows）获取内联辅助。

请参阅 AI 概览，了解如何配置服务商以及更多可能性。

正在从其他编辑器迁移？

我们提供了从其他编辑器切换的专用指南：

  • VS Code — 导入设置、映射键位、寻找等效功能
  • IntelliJ IDEA — 适应 Zed 的导航和重构方式
  • PyCharm — 在 Zed 中搭建 Python 开发环境
  • WebStorm — 配置 JavaScript/TypeScript 开发流程
  • RustRover — 在 Zed 中进行 Rust 开发

你还可以启用熟悉快捷键方案：

  • Vim：在设置中启用 vim_mode，详见 Vim Mode。
  • Helix：在设置中启用 helix_mode，详见 Helix Mode。

加入社区

Zed 是开源项目。欢迎在 GitHub 或 Discord 上加入我们，贡献代码、报告 bug 或提出功能建议。

macOS

Zed 主要在 macOS 上开发，因此 macOS 是受完整功能支持的一等平台。

安装 Zed

从下载页面下载 Zed。下载的是一个 .dmg 文件，打开后把 Zed 拖到 Applications 文件夹即可。

如果想用预览版（比稳定版提前约一周获得更新），请访问预览版发布页面。

安装后，Zed 会自动检查更新，并在有新版本时提示你。

Homebrew

也可以用 Homebrew 安装 Zed：

brew install --cask zed

安装预览版：

brew install --cask zed@preview

从源码构建

要从源码构建 Zed，请参阅 macOS 开发文档。

系统要求

Zed 使用 Metal 进行 GPU 加速渲染，所有受支持的 macOS 版本均可使用。

安装 CLI

Zed 自带命令行工具，可从 Terminal 打开文件和项目。安装步骤：

  1. 打开 Zed
  2. 按 Cmd+Shift+P 打开命令面板
  3. 运行 cli: install cli binary

这会在 /usr/local/bin 下创建 zed 命令。之后你可以打开文件或文件夹：

zed .                    # 打开当前文件夹
zed file.txt             # 打开文件
zed project/ file.txt    # 打开文件夹和文件

所有可用选项参见 CLI 参考。

卸载

  1. 如果 Zed 正在运行，先退出
  2. 将 Zed 从应用程序拖到废纸篓
  3. 可选：删除你的设置和扩展
rm -rf ~/.config/zed
rm -rf ~/Library/Application\ Support/Zed
rm -rf ~/Library/Caches/Zed
rm -rf ~/Library/Logs/Zed
rm -rf ~/Library/Saved\ Application\ State/dev.zed.Zed.savedState

如果安装了 CLI，请运行以下命令移除：

rm /usr/local/bin/zed

故障排查

Zed 无法打开或显示“已损坏”警告

如果 macOS 报告 Zed 已损坏或无法打开，可能是 Gatekeeper 问题。尝试：

  1. 在应用程序中右键（或 Control-点击）Zed
  2. 从右键菜单中选择“打开”
  3. 在弹出的对话框中点击“打开”

这将告知 macOS 信任该应用。

如果无效，请移除隔离属性：

xattr -cr /Applications/Zed.app

CLI 命令未找到

安装后如果 zed 命令不可用：

  1. 检查 /usr/local/bin 是否在 PATH 中
  2. 尝试在命令面板中通过 cli: install cli binary 重新安装 CLI
  3. 打开新的终端窗口以重新加载 PATH

无法安装 CLI

cli: install cli binary 会在 /usr/local/bin 目录下创建一个名为 zed 的符号链接，这需要管理员权限。如果你的 macOS 账户不属于 admin 用户组，Zed 无法创建该符号链接，并会提示无法自动安装 CLI。

作为替代方案，你可以添加一个别名，指向应用程序内部自带的 cli 二进制文件。具体路径取决于 Zed 的安装位置：

# 默认安装（Zed 位于 /Applications）
alias zed="/Applications/Zed.app/Contents/MacOS/cli"

# 用户安装（Zed 位于 ~/Applications）
alias zed="$HOME/Applications/Zed.app/Contents/MacOS/cli"

# 预览版构建（Zed Preview 位于 ~/Applications）
alias zed="$HOME/Applications/Zed Preview.app/Contents/MacOS/cli"

将与你安装方式匹配的那行配置添加到 shell 配置文件中。使用 Zsh（现代 macOS 的默认 shell）时请编辑 ~/.zshrc，使用 Bash 时则编辑 ~/.bashrc。

重启 shell 后，你就可以在终端中使用 zed 命令了：

zed .              # 打开当前文件夹
zed file.txt       # 打开文件

GPU 或渲染问题

Zed 使用 Metal 进行渲染。如果遇到图形故障，请尝试以下操作：

  1. 确保 macOS 已更新到最新版本
  2. 重启 Mac 以重置 GPU 状态
  3. 打开活动监视器，检查是否有其他应用占用大量 GPU 资源

内存或 CPU 占用过高

如果 Zed 的资源消耗超出预期：

  1. 在终端输出中检查是否有异常运行的语言服务器（zed: open log）
  2. 逐个禁用扩展，以排查是否存在冲突
  3. 对于大型项目，建议使用项目设置，将无关文件夹排除在索引范围之外

如需更多帮助，请参阅故障排查指南，或访问Zed Discord社区。

Linux

标准安装

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

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

我们还提供 Zed 的预览版，其更新比稳定版提前约一周发布。可用以下命令安装：

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

脚本安装的 Zed 在以下系统上运行效果最佳：

NixOS 默认没有系统级 glibc。如果你想在 NixOS 上使用我们提供的构建版本，可以安装 nix-ld 之类的 glibc 兼容层，或许能正常运行。

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

在 Linux 上安装 Zed 的其他方法

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

通过包管理器安装

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

在 Repology 上查看当前各大仓库中的 Zed 软件包列表。

社区

安装第三方软件包时请注意，其更新可能不及时，且与我们官方打包的 Zed 略有差异（例如，为避免与其他软件包冲突，二进制文件通常被重命名为 zedit 或 zeditor）。

我们很高兴能借助大家的努力，让 Zed 惠及更多用户。如果你的包管理器中尚无 Zed，且你愿意为此做出改变，可参考我们关于如何操作的说明。

本章节列出的软件包虽可安装 Zed 的二进制文件，但并非所属发行版的官方软件包。这些包由社区成员维护，安装时请格外谨慎。

手动下载

你也可通过下载我们预编译的 .tar.gz 安装包进行安装。此即安装脚本所使用的文件；如需自定义安装路径，可按下方说明调整：

下载 .tar.gz 文件：

请确保压缩包中的 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 命令加 --uninstall 参数来卸载：

zed --uninstall

注意，这种方式卸载的是符号链接所指向的那个 Zed 版本。如果你同时安装了多个版本（比如 Stable 和 Preview），就需要改用绝对路径来执行卸载，具体见下文。

如果没有报错，终端会询问你是保留还是删除个人偏好设置。做出选择后，你应该会看到 Zed 已成功卸载的提示。

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

$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-preview.app 版本），你需要调用该安装目录下的 zed 二进制文件，并按前面相同的格式加上 --uninstall 参数。

包管理器

如果 Zed 是通过包管理器安装的，请查阅该包管理器的文档，了解如何卸载软件包。

故障排查

# 在 Linux 上开发 Zed

Linux 运行在大量配置各异的系统上。我们主要在一个纯净的 Ubuntu 环境里测试 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 日志（~/.local/share/zed/logs/Zed.log）中搜索 Using GPU: ...，可以查看 Zed 当前使用的是哪块显卡。

若看到 ERROR_INITIALIZATION_FAILED、GPU Crashed 或 ERROR_SURFACE_LOST_KHR 等错误，可以尝试安装不同的 GPU 驱动或切换其他 GPU。参考 #14225。

在部分系统中，配置文件 /etc/prime-discrete 可用于通过 PRIME 机制强制使用独立显卡。根据具体的硬件环境，你可能需要将此文件的内容修改为 “on”（强制使用独显）或 “off”（强制使用集显）。

在其他系统中，你可以在运行 Zed 时设置环境变量 DRI_PRIME=1，以强制使用独立显卡。

如果你使用的是 AMD 显卡，可能会遇到 “Broken Pipe”（管道破裂）错误。尝试使用 RADV 或 Mesa 驱动。（参见 #13880）

如果你使用的是 amdvlk（默认的 AMD 开源图形驱动），可能会发现 Zed 无法启动。这是部分用户已知的兼容性问题，例如在 Omarchy 系统上（参见 issue #28851）。要修复此问题，你需要更换驱动。建议卸载 amdvlk 和 lib32-amdvlk 包，并安装 vulkan-radeon 作为替代（参见 issue #14141）。

如需更多详情，Arch 的 Vulkan 指南 提供了一些很好的步骤，这些步骤在大多数发行版中都适用。

强制 Zed 使用指定 GPU

有几种不同的方法可以强制 Zed 使用特定的 GPU：

选项 A

你可以使用环境变量 ZED_DEVICE_ID={device_id} 来指定希望 Zed 使用的 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 列表，然后导出 MESA_VK_DEVICE_SELECT=xxxx:yyyy 来选择指定设备。此外，还可以额外导出 WAYLAND_DISPLAY="" 回退到 xwayland。

方案 C

使用 vkdevicechooser。

报告图形问题

如果 Vulkan 配置正确但 Zed 仍然无法运行，请尽可能提供详细信息，提交 issue。

当 Zed 因图形初始化错误而无法启动时，往往无法按 issue 模板中的指引运行 zed: copy system specs into clipboard 命令。针对这种情况，我们提供了另一种收集系统规格的方法。

给 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 命令行工具，也可以这样：

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

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

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

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

```
{zed log contents}
```

</details>

这样日志会默认折叠，让 issue 更易读。

无法打开任何文件

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

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

Zed 没有记住我的 API Keys

Zed 没有记住我的登录状态

此功能同样依赖 XDG desktop portals，具体为：

Zed 需要安全存储 Zed 登录 Cookie、OpenAI API Keys 等机密信息，因此使用系统提供的密钥链。提供此功能的软件包示例包括 gnome-keyring、KWallet 和 keepassxc 等。

无法启动 inotify

Zed 依赖 inotify 监控文件系统变更。若无法启动 inotify，Zed 将无法可靠运行。

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

文件描述符耗尽也可能导致此问题。可用 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 资源数据库（xrdb）的 Xft.dpi
  3. 基于显示器分辨率和物理尺寸的 RandR 自动检测

如果你希望自定义缩放系数，超越 Zed 的自动检测范围，有几种可选方案：

查看当前缩放系数

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

xrdb -query | grep Xft.dpi

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

方案 1：设置 Xft.dpi（X 资源数据库）

Xft.dpi 是一个标准的 X11 设置，许多应用程序使用它来实现一致的字体和 UI 缩放。设置它可确保 Zed 与其他遵循此设置的 X11 应用程序拥有相同的缩放行为。

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

vim ~/.Xresources

添加一行，填入你期望的 DPI 值：

Xft.dpi: 96

常见的 DPI 取值：

加载配置：

xrdb -merge ~/.Xresources

重启 Zed 让改动生效。

方法二：使用 GPUI_X11_SCALE_FACTOR 环境变量

这个 Zed 专用的环境变量可以直接设置缩放比例，跳过所有自动检测逻辑。

GPUI_X11_SCALE_FACTOR=1.5 zed

可以使用小数（如 1.25、1.5、2.0），也可以设置 GPUI_X11_SCALE_FACTOR=randr，强制使用 RandR 检测，即使已设置了 Xft.dpi。

想让它永久生效，可以把这行加到 shell 配置文件或桌面入口文件中。

方法三：调整系统级 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

```
```

Windows

安装 Zed

通过下载页面获取最新稳定版构建。如需下载预览版，请前往其发布页面。首次手动安装后，Zed 会定期检查是否有安装更新。

你也可以从源码构建 Zed，请参阅相关文档获取说明。

包管理器

此外，你可以使用 winget 安装 Zed：

winget install -e --id ZedIndustries.Zed

卸载

你的配置和扩展保存在用户配置文件中。卸载时，可以选择保留或移除它们。

远程开发（SSH）

Zed 在 Windows 上通过 SSH 和 WSL 支持远程开发。你可以通过 SSH 连接远程服务器，也可以直接在 Zed 中操作 WSL 发行版中的文件。

关于远程开发功能的详细设置与使用说明，包括 SSH 配置、WSL 设置和故障排查，请参阅远程开发文档。

故障排查

Zed 无法启动或显示空白窗口

终端问题

如果激活脚本没有运行，请更新到最新版本，并确认你的 shell 配置文件没有提前退出。使用 Git 时，请确认 Git Bash 或 PowerShell 可用且已加入 PATH。

SSH 远程连接问题

输入凭据时请使用图形化 askpass 对话框。如果对话框没有出现，请检查是否存在凭据管理器冲突，以及终端是否阻止了 GUI 弹窗。

图形问题

Zed 无法打开 / 性能下降

Zed 需要支持 DirectX 11 的 GPU 才能运行。如果 Zed 无法打开，可能是你的 GPU 不满足最低要求。

要检查 GPU 是否支持 DirectX 11，可运行以下命令：

dxdiag

这会打开 DirectX 诊断工具，在 System → System Information → DirectX Version 下可以看到 GPU 支持的 DirectX 版本。

如果你在虚拟机中运行 Zed，它将使用虚拟机提供的模拟适配器。Zed 在这种环境下可以正常运行，但性能可能会有所下降。

使用调试器

Zed 通过 Debug Adapter Protocol (DAP) 为多种编程语言提供调试功能。DAP 是一个标准化协议，定义了调试器、编辑器和 IDE 之间的通信方式，让 Zed 无需为每种语言单独实现调试逻辑，就能支持各类调试器。Zed 实现了协议的客户端部分，各种调试适配器（debug adapter）则负责服务端部分。

借助这一协议，可以在不同编程语言和运行环境中以一致的方式设置断点、单步调试、查看变量等等。

支持的语言

要调试某种语言编写的代码，Zed 需要找到该语言对应的调试适配器。有些适配器由 Zed 内置提供、无需额外配置，有些则由语言扩展提供。目前已有调试适配器可用的语言如下：

如果你的语言不在列表中，欢迎为它添加 debug adapter 作出贡献。详情请参阅我们的 debugger extensions 文档。

点击上面的链接可以查看各语言和 adapter 的具体信息与示例；如需了解适用于所有 adapter 的 Zed 通用调试功能，请继续往下阅读。

快速上手

对大多数语言来说，最快的上手方式是运行 debugger: start（f4|f4）。这会打开 新进程模态窗口，其中按上下文列出当前项目预配置的调试任务。调试任务来自测试、入口点（如 main 函数）等来源——具体支持哪些，请查阅你所使用语言的文档。

也可以点击调试面板右上角的“加号”按钮打开同样的窗口。

对于没有提供预配置调试任务的语言（包括 C、C++ 以及部分由扩展支持的语言），你可以在项目根目录的 .zed/debug.json 文件中定义调试配置。该文件应是一个配置对象数组：

[
  {
    "adapter": "CodeLLDB",
    "label": "First configuration"
    // ...
  },
  {
    "adapter": "Debugpy",
    "label": "Second configuration"
    // ...
  }
]

针对典型使用场景的示例配置，请查阅你所使用语言的文档。把配置添加到 .zed/debug.json 后，它们会出现在新建进程对话框的列表中。

Zed 还会加载 .vscode/launch.json 中的调试配置，当 .zed/debug.json 中没有找到任何配置时，这些配置会显示在新建进程对话框里。

全局调试配置

如果你在多个项目中使用相同的启动配置，可以把它们统一存放在用户配置里。通过命令面板执行 zed: open debug tasksdebug.json 文件；Zed 会在用户 settings.json 旁边创建该文件，并保持它与调试器 UI 同步。文件路径如下：

这个文件的内容格式与 .zed/debug.json 相同，也是一个对象数组。其中定义的所有场景会合并到每个工作区，因此你常用的启动配置会自动出现在“New Debug Session”对话框中。

启动与附加

Zed 调试器提供了两种调试程序的方式：可以启动（launch）程序的新实例，也可以附加（attach）到已有的进程。具体选哪种，取决于你想实现的目标。

启动新实例时，由于 Zed（以及底层的 debug adapter）掌控着程序的完整生命周期，通常比附加到已有进程能更好地获取调试信息。运行单元测试或应用的 debug 构建，就是适合用启动方式的典型场景。

与直接启动相比，附加到已有进程看似逊色，实则不然。有时你无法承受重启程序的代价——比如 bug 只在生产环境中出现，无法在其他环境下复现。

配置

所有调试任务都需要填写 adapter 和 label 字段。此外，Zed 会用 build 字段在调试器启动前执行必要的准备工作（见下文），还支持 tcp_connection 字段来连接已存在的进程。

其余字段由调试适配器定义，并可以使用任务变量。大多数适配器支持 request、program 和 cwd：

[
  {
    // 调试配置的标签，用于在调试面板和新进程弹窗中标识调试会话
    "label": "Example Start debugger config",
    // Zed 用于调试程序的调试适配器
    "adapter": "Example adapter name",
    // Request：
    //  - launch：若指定了程序，Zed 会启动它；否则会打开一个配置正确的调试终端
    //  - attach：Zed 附加到正在运行的程序进行调试；未指定 process_id 时会显示进程选择器（目前仅 node 支持）
    "request": "launch",
    // 要调试的程序。该字段支持以 ~ 或 . 开头的路径解析。
    "program": "path_to_program",
    // cwd：默认为项目的当前工作目录（$ZED_WORKTREE_ROOT）
    "cwd": "$ZED_WORKTREE_ROOT"
  }
]

具体支持哪些字段，请查阅所用调试适配器的文档。

构建任务

Zed 允许在 build 字段中嵌入一个 Zed 任务，它会在调试器启动之前运行。这适用于在调试器启动前准备环境或执行必要的初始化步骤。

[
  {
    "label": "Build Binary",
    "adapter": "CodeLLDB",
    "program": "path_to_program",
    "request": "launch",
    "build": {
      "command": "make",
      "args": ["build", "-j8"]
    }
  }
]

构建任务也可以通过未替换的标签引用现有任务：

[
  {
    "label": "Build Binary",
    "adapter": "CodeLLDB",
    "program": "path_to_program",
    "request": "launch",
    "build": "my build task" // 也可以是 "my build task for $ZED_FILE"
  }
]

自动创建场景

针对 Zed 任务，Zed 可以自动为你创建场景。从行号槽（gutter）创建场景的功能也是基于这一机制实现的。 目前支持自动创建场景的语言有 Rust、Go、Python、JavaScript 和 TypeScript。

断点

设置断点很简单，只需点击编辑器行号槽中行号旁边的位置即可。 断点支持按需调整；要查看某个断点的更多选项，可以右键点击行号槽中的断点图标并选择所需的选项。 目前可以：

某些调试适配器（如 CodeLLDB 和 JavaScript）还会验证断点是否可能被命中；无法命中的断点会在界面中以更醒目的方式标出。

项目下所有已启用的断点也会列在调试会话界面的“Breakpoints”项中。在这里你还可以管理异常断点。 设置异常断点后，只要发生指定类型的异常，调试适配器就会停下。支持的异常类型取决于具体的调试适配器。

使用分屏

在打开多个分屏的情况下调试时，Zed 只会在其中一个窗格中显示当前调试行，其他窗格的布局保持不变。如果同一个文件在多个窗格中都打开，调试器会选择该文件已是活动标签页的那个窗格，而不会在其他窗格中切换标签页。

调试器一旦选定了某个面板，后续会话中命中断点时会继续使用该面板。如果你把带有当前调试行的标签页拖到其他分屏，调试器也会跟随移动，改用新的面板。

这样能保证调试器在跨文件单步调试时不会打乱你的工作流。

Settings

调试器的设置在 settings.json 中统一放在 debugger 键下：

Dock

可选值

  1. left - 调试面板停靠在界面左侧。
  2. right - 调试面板停靠在界面右侧。
  3. bottom - 调试面板停靠在界面底部。
"debugger": {
  "dock": "bottom"
},

Stepping granularity

可选值

  1. Statement - 单步执行会让程序运行到当前语句执行完毕。 语句的定义由适配器决定，可能等同于一行。比如 for(int i = 0; i < 10; i++) 可以被看作包含 3 条语句：int i = 0、i < 10 和 i++。
{
  "debugger": {
    "stepping_granularity": "statement"
  }
}
  1. Line - 单步执行到当前源码行运行完毕。
{
  "debugger": {
    "stepping_granularity": "line"
  }
}
  1. Instruction - 单步执行一条指令（例如一条 x86 指令）。
{
  "debugger": {
    "stepping_granularity": "instruction"
  }
}

Save Breakpoints

可选值

boolean 类型

{
  "debugger": {
    "save_breakpoints": true
  }
}

Button

可选值

boolean 类型

{
  "debugger": {
    "button": true
  }
}

Timeout

可选值

integer 类型

{
  "debugger": {
    "timeout": 3000
  }
}

Inline Values

可选值

{
  "inlay_hints": {
    "show_value_hints": false
  }
}

也可以通过编辑器工具栏中的 Editor Controls 菜单切换内联值提示。

Log Dap Communications

可选项

boolean 类型

{
  "debugger": {
    "log_dap_communications": true
  }
}

格式化 DAP 日志消息

可选项

boolean 类型

{
  "debugger": {
    "format_dap_log_messages": true
  }
}

自定义调试适配器

你可以只设置 binary、只设置 args，或两者都设置。注意 binary 应指向调试适配器（如 lldb-dap），而不是调试器本身（如 lldb）。args 会覆盖 Zed 原本传给适配器的所有参数。

{
  "dap": {
    "CodeLLDB": {
      "binary": "/Users/name/bin/lldb-dap",
      "args": ["--wait-for-debugger"]
    }
  }
}

主题

调试器支持以下主题选项：

故障排查

如果调试器遇到问题，请在 GitHub 上提交 issue，并尽量提供详细的上下文信息。你也可以借助以下功能收集更多问题线索：

性能

Zed 是一款开源代码编辑器，内置协作和 AI 工具。

本指南介绍常用命令、环境配置和基础导航。

快速上手

欢迎页

在没有打开任何文件夹时启动 Zed，主编辑区会显示欢迎页。欢迎页提供了一些快捷操作：打开文件夹、克隆仓库或查看文档。一旦打开文件夹或文件，欢迎页就会消失。如果你把编辑器拆分成多个窗格，欢迎页只会在中间窗格为空时出现，其他窗格则显示标准的空状态。

要重新打开欢迎页，可以关闭中间窗格中的所有项目，或者在命令面板中搜索“Welcome”。

1. 打开项目

从命令行打开文件夹：

zed ~/projects/my-app

也可以在 Zed 内使用 Cmd+O（macOS）或 Ctrl+O（Linux/Windows）打开文件夹。

默认情况下，新项目会在当前窗口的线程侧边栏中打开。如果想在独立的新窗口打开，可以使用 zed -n ~/projects/my-app，或在 Open Recent 列表中选择时按 Cmd+Enter。详情请参阅 Windows & Projects。

2. 掌握基本命令

操作macOSLinux/Windows
命令面板Cmd+Shift+PCtrl+Shift+P
跳转到文件Cmd+PCtrl+P
跳转到符号Cmd+Shift+OCtrl+Shift+O
项目内查找Cmd+Shift+FCtrl+Shift+F
切换终端Ctrl+`Ctrl+`
打开设置Cmd+,Ctrl+,

命令面板（Cmd+Shift+P）是使用 Zed 所有功能的入口。如果忘了某个快捷键，直接在里面搜索即可。

面板布局

想让 Agent Panel 和线程侧边栏并排显示在左侧，可从标题栏的用户菜单选择 Panel Layout > Agentic（或执行 workspace: use agentic layout）。想恢复以编辑器为主的经典布局，则选择 Panel Layout > Classic（或执行 workspace: use classic layout）。

3. 配置编辑器

用 Cmd+,（macOS）或 Ctrl+,（Linux/Windows）打开设置编辑器，搜索任意设置项并直接修改。

常见的第一批调整：

4. 配置语言支持

Zed 内置支持多种语言，其他语言可通过安装扩展来支持：

  1. 用 Cmd+Shift+X（macOS）或 Ctrl+Shift+X（Linux/Windows）打开 Extensions 面板
  2. 搜索你的语言
  3. 点击 Install

各种语言的配置说明请参阅 Languages。

5. 体验 AI 功能

Zed 内置了 AI 助手。用 Cmd+Shift+A（macOS）或 Ctrl+Shift+A（Linux/Windows）打开 Agent Panel 开始对话，也可以用 Cmd+Enter（macOS）/ Ctrl+Enter（Linux/Windows）获取行内辅助。

配置 AI 服务商及了解可用的功能，请参阅 AI Overview。

从其他编辑器迁移过来？

我们为从其他编辑器迁移的用户准备了专门的指南：

你也可以启用熟悉的按键模式：

加入社区

Zed 是开源项目。欢迎通过 GitHub 或 Discord 参与贡献代码、报告问题或提出功能建议。

上一篇
第102章 Zed 编辑器快速上手指南

本篇用到的工具

Zed
Zed
Zed 是一款面向速度和协作的极简 code editor，专为现代开发者打造。它原生支持与 AI agent 实时 pair programming，并内置多人协作编辑功能，让团队成员能在同一文件中同步 coding。极低延迟与轻量架构使其在大型项目与多文件操作中依然保持流畅响应，适用于 macOS、Linux 等跨平台开发场景。

评论 (0)