第61章 Zed 编辑器 C++ 支持配置指南

Zed 原生支持 C++。

• Tree-sitter: tree-sitter/tree-sitter-cpp
• Language Server: clangd/clangd

二进制文件

你可以配置 Zed 使用的 clangd 二进制文件。

默认情况下，Zed 会尝试在 $PATH 中查找 clangd 并使用它。如果该二进制文件成功执行，Zed 就会使用它。否则，Zed 会回退到安装自带的 clangd 版本并使用该版本。

如果你想安装 clangd 的预发布版本，可以在 settings.json 中将 pre_release 设置为 true：

{
  "lsp": {
    "clangd": {
      "fetch": {
        "pre_release": true
      }
    }
  }
}

如果你想禁止 Zed 查找系统上的 clangd 二进制文件，可以在 settings.json 中将 ignore_system_version 设置为 true：

{
  "lsp": {
    "clangd": {
      "binary": {
        "ignore_system_version": true
      }
    }
  }
}

如果你想使用自定义位置的二进制文件，可以指定 path 和可选的 arguments：

{
  "lsp": {
    "clangd": {
      "binary": {
        "path": "/path/to/clangd",
        "arguments": []
      }
    }
  }
}

这里的 "path" 必须是绝对路径。

参数

你可以向 clangd 传递任意数量的参数。要查看完整的可用选项列表，请从命令行运行 clangd --help。例如，使用 --function-arg-placeholders=0 时，代码补全仅包含函数调用的括号；而默认设置（--function-arg-placeholders=1）下的代码补全还会包含方法参数的占位符。

{
  "lsp": {
    "clangd": {
      "binary": {
        "path": "/path/to/clangd",
        "arguments": ["--function-arg-placeholders=0"]
      }
    }
  }
}

格式化

默认情况下，Zed 会使用 clangd 语言服务器来格式化 C++ 代码，其格式化能力与 clang-format 命令行工具相同。要自定义格式化规则，可以添加一个 .clang-format 文件，例如：

# yaml-language-server: $schema=https://json.schemastore.org/clang-format-21.x.json
---
BasedOnStyle: LLVM
IndentWidth: 4
---
Language: Cpp
# Force pointers to the type for C++.
DerivePointerAlignment: false
PointerAlignment: Left
---

完整配置选项请参阅 Clang-Format Style Options。

你可以通过 {#kb editor::Format} 快捷键、命令面板中的 {#action editor::Format} 操作，或开启保存时自动格式化来触发格式化。

在设置（{#kb zed::OpenSettings}）中的 Languages > C++ 下进行配置，或直接在设置文件中添加：

  "languages": {
    "C++": {
      "format_on_save": "on",
      "tab_size": 2
    }
  }

更多服务器配置

通常可以在项目根目录下创建一个 .clangd 文件来设置额外的配置。

# yaml-language-server: $schema=https://json.schemastore.org/clangd.json
CompileFlags:
  Add:
    - "--include-directory=/path/to/include"
Diagnostics:
  MissingIncludes: Strict
  UnusedIncludes: Strict

clangd 配置文件的更多高级用法请查看其官方文档。

Compile Commands

某些项目中，Clangd 需要一个 compile_commands.json 文件才能正确分析代码。该文件包含编译数据库，告诉 clangd 项目应如何构建。

CMake Compile Commands

使用 CMake 时，只需在 CMakeLists.txt 中加入下面这行，即可自动生成 compile_commands.json：

set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

构建项目后，CMake 会在构建目录中生成 compile_commands.json，clangd 会自动读取它。

调试

你可以使用 CodeLLDB 或 GDB 来调试原生二进制文件。（请确保构建过程向 C++ 编译器传递了 -g 参数，以便最终生成的二进制文件包含调试信息。）关于可添加到 .zed/debug.json 的调试配置示例，请参见下文。

• CodeLLDB 配置文档
• GDB 配置文档
  • GDB 版本需至少为 v14.1

构建与调试二进制文件

[
  {
    "label": "Debug native binary",
    "build": {
      "command": "make",
      "args": ["-j8"],
      "cwd": "$ZED_WORKTREE_ROOT"
    },
    "program": "$ZED_WORKTREE_ROOT/build/prog",
    "request": "launch",
    "adapter": "CodeLLDB"
  }
]

协议扩展

Zed 目前实现了 clangd 的以下扩展：

非活跃区域

由于预处理指令（例如求值为 false 的 #if、#ifdef 或 #ifndef 代码块），会自动变暗非活跃的代码区域。

在源文件和头文件间切换

允许在对应的 C++ 源文件（例如 .cpp）和头文件（例如 .h）之间进行切换。 你可以通过在命令面板中运行 {#action editor::SwitchSourceHeader} 命令，或者为 editor::SwitchSourceHeader 动作设置按键绑定来实现。

{
  "context": "Editor",
  "bindings": {
    "alt-enter": "editor::SwitchSourceHeader"
  }
}