第51章 Zed 编辑器 Vim 模式详解

Zed 内置了 Vim 模拟层。本页面介绍如何启用和禁用 vim 模式、键位绑定、Zed 特有的功能以及配置选项。

Zed vim 模式的设计理念

vim 模式在合理之处复刻了 Vim 的移动（motions）和命令行为，而在 Zed 方案更优之处则采用 Zed 专属功能。目标是提供开箱即用的熟悉体验，无需额外配置。

这包括对语义导航、多光标的支持，以及其他通常由插件提供的功能，例如包围文本（surrounding text）。

因此，Zed 的 vim 模式并非与 Vim 一比一复刻，而是将 Vim 的模态设计与 Zed 的现代特性相结合，带来更流畅的体验。该模式支持配置，你可以添加自定义键位绑定或覆盖默认设置。

核心差异

vim 模式中有四类功能使用了 Zed 的核心能力，导致部分行为存在差异：

1. 移动（Motions）：vim 模式利用 Zed 的语义解析，针对不同语言调整移动行为。例如，在 Rust 中，使用 % 跳到匹配括号时支持管道符 |；在 JavaScript 中，w 将 $ 视为单词字符。
2. 视觉块选择（Visual block selections）：vim 模式借助 Zed 的多光标功能模拟视觉块选择，使块选择更加灵活。例如，在块选择后插入的文本会实时更新到每一行，且可随时增删光标。
3. 宏（Macros）：vim 模式使用 Zed 的录制系统来处理 vim 宏。因此，可以捕获并回放更复杂的操作，比如自动补全。
4. 查找与替换（Search and replace）：vim 模式使用 Zed 的搜索系统，因此正则表达式语法与 Vim 略有不同。查看正则表达式差异部分了解详情。

注意：Zed vim 模式的基础功能已能覆盖许多使用场景，且我们正持续优化。如果发现工作流中缺失的功能，请在 GitHub 上提交 issue。

启用与禁用 vim 模式

首次打开 Zed 时，欢迎页面上会有一个复选框，允许你启用 vim 模式。

如果你之前错过了这个：随时都可以打开命令面板，使用 workspace 命令 {#action workspace::ToggleVimMode} 来开启或关闭 vim mode。

注意：这个命令会切换用户设置中的以下属性：

{
  "vim_mode": true
}

Zed 特有功能

Zed 构建在现代技术基础之上，利用 Tree-sitter 和 language server 理解你正在编辑的文件内容，并且原生支持多光标。

Vim mode 提供了一些 Zed 核心快捷键，帮你充分发挥 Zed 的特色功能。

Language server

以下命令借助 language server 帮你导航和重构代码。

Git

Tree-sitter

Tree-sitter 是 Zed 用来解析代码结构的底层引擎。Zed 提供了一系列移动命令来改变光标位置，并支持将文本对象作为操作的目标。

注意：[m 系列移动命令的目标边界定义与 af 一致。[[ 的目标与 ac 的定义相同，但若代码中不存在类，则会退回使用函数作为目标。同样地，g c 用于定位 [ /。

函数、类和注释的定义因语言而异。扩展可以通过添加 textobjects.scm 文件来获得支持。参数和标签的定义则运行在 Tree-sitter 层面，它会在解析树中查找特定模式，目前尚不支持按语言进行配置。

多光标

这些命令帮助你管理 Zed 中的多个光标。

窗格管理

这些命令用于打开新窗格或跳转到指定窗格。

插入模式

以下命令可帮助你在不退出插入模式的情况下调出 Zed 的补全菜单、请求 GitHub Copilot 建议或打开内联 AI 助手。

支持的插件功能

Zed 的 vim 模式内置了 Vim 生态中常用插件提供的功能：

• 可以用 ys（yank surround）为文本对象添加包围符，用 cs 更换包围符，用 ds 删除包围符。
• 可以在可视模式下用 gc、在普通模式下用 gcc 切换注释。
• 项目面板支持许多仿照 Vim 插件 netrw 的快捷键：用 hjkl 导航，用 o 打开文件，用 t 在新标签页打开文件，等等。
• 可以在 keymap 中添加按键绑定，以便在"camelCase"命名中移动。具体做法见下文可选按键绑定一节。
• 可以用 gR 实现 ReplaceWithRegister 的功能。
• 可以用 cx 实现 vim-exchange 的功能。注意它在可视模式下没有默认绑定，但你可以在 keymap 中自行添加（参见可选按键绑定一节）。
• 可以用 indent wise 插件的 [-、]-、[+、]+、[=、]= 在相对于光标的缩进层级间移动。
• 可以用 AnyQuotes 选择引号内文本，用 AnyBrackets 选择括号内文本。Zed 还提供 MiniQuotes 和 MiniBrackets，其选择行为基于 Neovim 插件 mini.ai。详见下文引号与括号文本对象一节。
• 可以为 AnyQuotes、AnyBrackets、MiniQuotes、MiniBrackets 配置不同的选择策略来选取引号和括号内的文本。详见下文Any Bracket 功能一节。

Any Bracket 功能

Zed 提供了两种不同的策略来选取被引号或方括号包围的文本。这些文本对象默认未启用，必须在你的键位映射配置中进行设置后方可使用。

包含的字符

每种文本对象类型适用于特定的字符：

“Any”和“Mini”两种变体适用于相同的字符集，但选取策略有所不同。

AnyQuotes 和 AnyBrackets（传统 Vim 行为）

这些文本对象实现了传统 Vim 的行为：

• 选取优先级：优先查找最内层（最近）的引号或括号
• 回退机制：若未找到，则回退到当前行
• 基于字符的匹配：仅关注开闭字符，不考虑语法结构
• 与原版 Vim 的一致性：AnyBrackets 的行为与原版 Vim 中如 ci<、ci( 等命令一致，包括可能的边界情况（例如将 => 中的 > 视为闭合分隔符）

MiniQuotes 和 MiniBrackets（mini.ai 行为）

这些文本对象实现了 mini.ai Neovim 插件的行为：

• 选取优先级：先搜索当前行，再向外扩展
• Tree-sitter 集成：使用 Tree-sitter 查询以实现更具上下文感知的选取
• 语法感知匹配：能够区分实际括号与其他上下文中的相似字符（例如 => 中的 >）

选择何种方法

• 如果你符合以下情况，建议使用 AnyQuotes/AnyBrackets：

  • 偏好传统 Vim 行为
  • 希望保持基于字符的选取一致性，并优先处理最内层分隔符
  • 需要行为与原版 Vim 文本对象紧密匹配

• 如果你符合以下情况，请使用 MiniQuotes/MiniBrackets：

  • 更倾向于 mini.ai 插件的行为
  • 希望使用 Tree-sitter 实现更具上下文感知的选择
  • 搜索时更倾向于当前行优先

配置示例

要使用这些文本对象，需要在键位映射中添加绑定。以下是一个配置示例，使得在使用文本对象操作符（i 和 a）或更改环绕（cs）时，这些对象可用：

{
  "context": "vim_operator == a || vim_operator == i || vim_operator == cs",
  "bindings": {
    // Traditional Vim behavior
    "q": "vim::AnyQuotes",
    "b": "vim::AnyBrackets",

    // mini.ai plugin behavior
    "Q": "vim::MiniQuotes",
    "B": "vim::MiniBrackets"
  }
}

使用此配置后，你可以使用如下命令：

• cib - 使用 AnyBrackets 行为更改括号内部
• ciB - 使用 MiniBrackets 行为更改括号内部
• ciq - 使用 AnyQuotes 行为更改引号内部
• ciQ - 使用 MiniQuotes 行为更改引号内部

命令面板

Vim 模式允许你使用 : 打开 Zed 的命令面板。然后你可以输入内容来访问任何常规 Zed 命令。此外，vim 模式为流行的 Vim 命令添加了别名，以确保你的肌肉记忆能转移到 Zed。例如，你可以输入 :w 或 :write 来保存文件。

下方，你可以找到表格，列出了在命令面板中可使用的命令。我们用方括号表示可选字符，意味着你可以省略它们。

注意：我们尚未模拟 Vim 命令行的完整功能。特别是，命令目前不支持参数。如果你在命令面板中发现缺失的功能，请在 GitHub 上提交问题。

文件和窗口管理

此表格展示了用于管理窗口、标签页和窗格的命令。由于命令目前不支持参数，在保存或创建新文件时，无法指定文件名。

注意：! 字符用于强制执行命令，不保存更改或在覆盖文件前不做提示。

Ex 命令

以下 ex 命令用于打开 Zed 的各个面板和窗口。

导航诊断

以下命令用于导航诊断信息。

Git

以下命令用于与版本控制系统 git 交互。

跳转

以下命令用于跳转到文件中的特定位置。

替换

此命令用于替换文本。它模拟了 vim 中的 substitute 命令。该命令使用正则表达式，且 Zed 的语法与 vim 略有不同。你可以在下方的 正则表达式差异章节 中了解 Zed 语法的更多细节。Zed 默认只替换当前行中搜索模式的首个匹配项。要替换所有匹配项，请添加 g 标志。

编辑

以下命令协助你编辑文本。

Set

这些命令用于局部修改当前缓冲区中的编辑器选项。

命令助记符

Zed 默认不提供任何命令助记符，但你可以通过在配置文件中设置 command_aliases 来为 Zed 命令定义简短别名。当你在命令面板中输入此映射中的别名时，它会被解析为对应的命令。

配置示例

要配置命令助记符，请在配置文件中添加 command_aliases 键。以下是一个包含有用助记符的配置示例：

{
  "command_aliases": {
    "zlog": "zed::OpenLog",
    "newf": "workspace::NewFile",
    "diffs": "editor::ToggleSelectedDiffHunks",
    "crp": "workspace::CopyRelativePath",
    "cpp": "workspace::CopyPath",
    "reveal": "editor::RevealInFileManager",
    "clank": "editor::CancelLanguageServerWork"
  }
}

通过此配置，你可以使用如下命令：

• :zlog - 打开 Zed 日志
• :newf - 创建新文件
• :diffs - 切换选中的差异代码块
• :crp - 复制当前文件的相对路径
• :cpp - 复制当前文件的完整路径
• :reveal - 在文件管理器中显示当前文件
• :clank - 取消语言服务器正在执行的任务

自定义按键绑定

选择正确的 context

Zed 的按键绑定只有在 "context" 属性与编辑器当前所处的位置匹配时才会生效。例如，把按键绑定添加到 "Editor" context，那么它们只会在编辑文件时起作用；如果添加到 "Workspace" context，则在 Zed 的任何地方都有效。下面是一个在编辑文件时执行保存的按键绑定示例：

{
  "context": "Editor",
  "bindings": {
    "ctrl-s": "workspace::Save"
  }
}

context 是嵌套的：当你编辑文件时，所处的 context 是 "Editor"，它位于 "Pane" 之内，而 "Pane" 又位于 "Workspace" 之内。这就是为什么添加到 "Workspace" context 的按键绑定在编辑文件时也能生效。请看示例：

// 这个按键绑定在编辑文件时生效。Zed 默认已内置了它，对应 workspace: save 命令。
{
  "context": "Workspace",
  "bindings": {
    "ctrl-s": "workspace::Save"
  }
}

context 是表达式，支持 &&（与）和 ||（或）等布尔运算符。例如，可以使用 "Editor && vim_mode == normal" 这个 context，创建只在编辑文件且处于 vim normal 模式时才生效的按键绑定。

Vim mode 在 "Editor" context 的基础上增加了几个 context：

注意：上下文一次只匹配一层。因此可以使用表达式 "Editor && vim_mode == normal"，但 "Workspace && vim_mode == normal" 永远不会匹配，因为我们在 "Editor" 层级设置 Vim 上下文。

Vim 模式按键绑定的常用上下文

下面是一个包含常用 Vim 模式上下文的模板，帮助你自定义 Vim 模式按键绑定。你可以复制并将其整合到你的用户键位映射中。

[
  {
    "context": "VimControl && !menu",
    "bindings": {
      // 如果你想让按键绑定在 normal 和 visual 模式下生效，请在此处添加。
    }
  },
  {
    "context": "vim_mode == normal && !menu",
    "bindings": {
      // "shift-y": ["workspace::SendKeystrokes", "y $"] // 使用 Neovim 的 yank 行为：复制到行尾。
    }
  },
  {
    "context": "vim_mode == insert",
    "bindings": {
      // "j k": "vim::NormalBefore" // 在插入模式下，按 jk 退出到普通模式。
    }
  },
  {
    "context": "EmptyPane || SharedScreen",
    "bindings": {
      // 如果想让按键绑定在没有编辑器存在时也能工作，请在此处（以及上述上下文的基础上）添加。
      // "space f": "file_finder::Toggle"
    }
  }
]

提示：如果你想模拟 Vim 的 map 命令（如 nmap 等），可以在正确的上下文中使用 workspace::SendKeystrokes 动作。

可选的按键绑定

默认情况下，你可以使用快捷键在编辑器中打开的不同文件之间导航：先按 ctrl+w，再按 h、j、k、l 分别向左、下、上、右移动。

但同样的快捷键无法用于在所有的编辑器停靠面板（终端、项目面板、Agent 面板等）之间切换。如果你希望使用相同的快捷键来导航这些面板，可以将以下按键绑定添加到你的用户按键映射中。

{
  "context": "Dock",
  "bindings": {
    "ctrl-w h": "workspace::ActivatePaneLeft",
    "ctrl-w l": "workspace::ActivatePaneRight",
    "ctrl-w k": "workspace::ActivatePaneUp",
    "ctrl-w j": "workspace::ActivatePaneDown"
    // ... 或其他按键绑定
  }
}

子词移动（Subword motion）功能允许你在 camelCase 或 snake_case 中导航和选中的是单个单词，默认未启用。若要启用，请将以下绑定添加到你的按键映射中。

{
  "context": "VimControl && !menu && vim_mode != operator",
  "bindings": {
    "w": "vim::NextSubwordStart",
    "b": "vim::PreviousSubwordStart",
    "e": "vim::NextSubwordEnd",
    "g e": "vim::PreviousSubwordEnd"
  }
}

提示：像 dw 这样的操作不受影响。如果希望这些操作也使用子词移动，请从 context 中移除 vim_mode != operator。

Vim 模式提供了在普通模式下环绕选区的快捷键（ys），但没有提供在可视模式下添加环绕的快捷键。默认情况下，shift-s 会替换选区（擦除文本并进入插入模式）。若要使用 shift-s 在可视模式下添加环绕，可将以下对象添加到你的按键映射中。

{
  "context": "vim_mode == visual",
  "bindings": {
    "shift-s": "vim::PushAddSurrounds"
  }
}

在非模态编辑器中，光标移动到行尾时通常会换到下一行。但 Zed 默认的行为和 Vim 完全一致：光标会停在行边界。如果你希望光标在行间换行移动，可以覆盖以下键绑定：

// 在 VimScript 中等价于：
// set whichwrap+=<,>,[,],h,l
{
  "context": "VimControl && !menu",
  "bindings": {
    "left": "vim::WrappingLeft",
    "right": "vim::WrappingRight",
    "h": "vim::WrappingLeft",
    "l": "vim::WrappingRight"
  }
}

Sneak motion 功能可以快速跳转到文本中任意两个字符的位置。要启用它，只需在 keymap 中添加以下键绑定。默认情况下 s 键映射为 vim::Substitute，添加这些绑定会覆盖该行为，请确认这符合你的使用习惯。

{
  "context": "vim_mode == normal || vim_mode == visual",
  "bindings": {
    "s": "vim::PushSneak",
    "shift-s": "vim::PushSneakBackward"
  }
}

Helix 风格的 jump-to-word 操作会在可见的单词开头显示跳转标签。该功能在 Vim 模式中没有默认绑定，需要在 keymap 中添加键绑定才能启用。下面的示例使用 g w，这与 Helix 的默认绑定一致，但会覆盖 Vim 模式默认的重新换行绑定。

{
  "context": "vim_mode == normal || vim_mode == visual",
  "bindings": {
    "g w": "vim::HelixJumpToWord"
  }
}

vim-exchange 功能在 visual 模式下没有默认绑定，因为 shift-x 会与 visual 模式默认的 shift-x 绑定（vim::VisualDeleteLine）冲突。如果要设置 vim-exchange 的默认绑定，可以在 keymap 中添加以下键绑定：

{ "context": "vim_mode == visual", "bindings": { "shift-x": "vim::Exchange" } }

恢复常用文本编辑和 Zed 快捷键

如果你是在 Linux 或 Windows 上使用 Vim 模式，可能会发现它覆盖了那些你离不开的快捷键，比如 ctrl+v 粘贴、ctrl+f 搜索等。你可以通过将以下数据复制到自己的键位映射配置中来恢复这些快捷键：

{ "context": "Editor && !menu", "bindings": { "ctrl-f": "buffer_search::Deploy", // Vim 默认：翻页向下 "ctrl-c": "editor::Copy", // Vim 默认：返回普通模式 "ctrl-x": "editor::Cut", // Vim 默认：减少 "ctrl-v": "editor::Paste", // Vim 默认：可视化块模式 "ctrl-a": "editor::SelectAll", // Vim 默认：增加 "ctrl-y": "editor::Undo", // Vim 默认：向上移动一行 "ctrl-t": "project_symbols::Toggle", // Vim 默认：跳转到较旧的标签 "ctrl-o": "workspace::Open", // Vim 默认：后退 "ctrl-s": "workspace::Save", // Vim 默认：显示签名 "ctrl-b": "workspace::ToggleLeftDock" // Vim 默认：向下移动 } }

修改 Vim 模式设置

你可以修改以下设置来调整 Vim 模式的行为：

这是一个添加 zombie emoji（僵尸表情）digraph 的示例。配置后，输入 ctrl-k f z 即可插入僵尸表情。你可以添加任意数量的 digraphs。

{
  "vim": {
    "custom_digraphs": {
      "fz": "🧟‍♀️"
    }
  }
}

以下是修改这些设置后的示例：

{
  "vim": {
    "default_mode": "insert",
    "use_system_clipboard": "never",
    "use_smartcase_find": true,
    "use_regex_search": true,
    "gdefault": true,
    "toggle_relative_line_numbers": true,
    "highlight_on_yank_duration": 50,
    "custom_digraphs": {
      "fz": "🧟‍♀️"
    }
  }
}

Vim 模式下有用的 Zed 核心设置

以下是一些通用 Zed 设置，有助于微调你的 Vim 体验：

以下是修改这些设置后的示例：

{
  // 禁用光标闪烁
  "cursor_blink": false,
  // 使用相对行号
  "relative_line_numbers": "enabled",
  // 隐藏滚动条
  "scrollbar": { "show": "never" },
  // 禁止缓冲区滚动超出最后一行
  "scroll_beyond_last_line": "off",
  // 允许光标到达屏幕边缘
  "vertical_scroll_margin": 0,
  "gutter": {
    // 完全禁用行号
    "line_numbers": false
  },
  "command_aliases": {
    "W": "w",
    "Wq": "wq",
    "Q": "q"
  }
}

command_aliases 是一个对象，用于把按键或按键序列映射到 vim mode 命令。上面的例子定义了多个别名：W 映射到 w、Wq 映射到 wq、Q 映射到 q。

正则表达式差异

Zed 使用的正则表达式引擎与 Vim 不同，因此在某些情况下需要使用不同的语法。以下是常见的差异：

• 捕获组：Vim 使用 \( 和 \) 表示捕获组，而在 Zed 中是 ( 和 )。反过来，在 Vim 中，( 和 ) 表示字面括号，但在 Zed 中必须转义为 \( 和 \)。
• 匹配引用：替换时，Vim 使用反斜杠后跟数字来表示已匹配的捕获组，例如 \1。Zed 则使用美元符号。也就是说，在 Vim 中用 \0 表示整个匹配时，在 Zed 中语法是 $0。编号捕获组同理：Vim 中的 \1 在 Zed 中是 $1。
• 全局选项：默认情况下，Vim 的正则搜索只匹配每行中的首次出现，你需要在查询末尾添加 /g 以查找所有匹配。而在 Zed 中，正则搜索默认就是全局的。
• 大小写敏感性：Vim 使用 /i 表示忽略大小写的搜索。在 Zed 中，你可以在模式开头写 (?i)，或者通过快捷键 {#kb search::ToggleCaseSensitive} 切换大小写敏感性。

提示：为了方便过渡，当你编写 Vim 风格的替换命令 :%s// 时，命令面板会自动修正括号并替换组。例如，Zed 会将 %s:/\(a\)(b)/\1/ 转换为搜索 "(a)(b)" 并替换为 "$1"。

关于 Zed 正则引擎支持的完整语法，请参阅 regex 文档。