Zed 诊断（Diagnostics）详解：语言服务器错误、警告的查看、过滤与跳转

本文基于 Zed 仓库中的官方文档 docs/src/diagnostics.md 展开，讲解 Zed 如何从语言服务器（LSP）获取诊断信息，并在编辑器、滚动条、项目面板与标签页等不同界面位置呈现错误与警告。读完本文，你将掌握 diagnostics_max_severity、scrollbar.diagnostics、diagnostics.inline、project_panel.show_diagnostics、tabs.show_diagnostics 等全部相关配置项的取值与默认值，以及 editor::GoToDiagnostic、editor::GoToPreviousDiagnostic 等导航动作的使用方法，并能对照源码理解这些设置背后的实现逻辑。

诊断信息的来源：同时支持 push 与 pull 两种 LSP 机制

Zed 的诊断信息来自语言服务器（Language Server）。根据 docs/src/diagnostics.md 的说明，Zed 同时兼容 LSP 的 push（服务端主动推送 textDocument/publishDiagnostics）与 pull（客户端主动请求 textDocument/diagnostic）两种变体，因此可以与所有现存的语言服务器配合工作。

这一“pull 诊断”能力在默认配置中就有对应的开关，见 assets/settings/default.json：

"diagnostics": {
  // Whether to show the project diagnostics button in the status bar.
  "button": true,
  // Whether to show warnings or not by default.
  //
  // Default: true
  "include_warnings": true,
  // Settings for using LSP pull diagnostics mechanism in Zed.
  "lsp_pull_diagnostics": {
    // Whether to pull for diagnostics or not.
    "enabled": true,
    // Minimum time to wait before pulling diagnostics from the language server(s).
    // 0 turns the debounce off.
    "debounce_ms": 50
  },
  // Settings for inline diagnostics
  "inline": {
    // Whether to show diagnostics inline or not
    "enabled": false,
    // The delay in milliseconds to show inline diagnostics after the
    // last diagnostic update.
    "update_debounce_ms": 150,
    // The amount of padding between the end of the source line and the start
    // of the inline diagnostic in units of em widths.
    "padding": 4,
    // The minimum column to display inline diagnostics.
    "min_column": 0,
    // The minimum severity of the diagnostics to show inline.
    // Inherits editor's diagnostics' max severity settings when `null`.
    "max_severity": null
  }
}

也就是说，diagnostics.lsp_pull_diagnostics.enabled 默认为 true，Zed 会按 debounce_ms（默认 50 毫秒，设为 0 可关闭防抖）的节流主动向语言服务器拉取诊断；而 diagnostics.include_warnings 控制项目诊断视图中是否默认显示警告。

在类型层面，诊断的严重级别在 crates/project/src/project_settings.rs 中定义为 DiagnosticSeverity 枚举（Off、Error、Warning、Info、Hint），该枚举派生了 Ord/PartialOrd，为后续按级别过滤提供了排序依据。

常规诊断：编辑器下划线与滚动条指示

默认情况下，Zed 会把所有诊断以下划线文本的形式渲染在编辑器内，同时在滚动条上给出对应的指示标记。两处渲染分别受两个配置项控制。

编辑器内下划线的严重级别过滤：diagnostics_max_severity

"diagnostics_max_severity": null

该编辑器设置的可能取值为 "off"、"error"、"warning"、"info"、"hint"、null（默认，显示全部诊断）。在 assets/settings/default.json 中其实际默认值写作 "all"，即不过滤任何级别。

从源码结构看，这个配置在设置内容层对应 DiagnosticSeverityContent 枚举（Off、Error、Warning、Info、Hint、All），定义于 crates/settings_content/src/project.rs；解析后的编辑器设置则保存在 crates/editor/src/editor_settings.rs 的 diagnostics_max_severity: Option<DiagnosticSeverity> 字段中。

需要注意的一个边界：该设置只影响编辑器内的诊断渲染，不会中断诊断的抓取，也不影响项目诊断视图（对应源码注释中 “Affects the editor rendering only, and does not interrupt the functionality of diagnostics fetching and project diagnostics editor”）。

滚动条指示的过滤：scrollbar.diagnostics

"scrollbar": {
  "diagnostics": "all"
}

可能取值为 "none"、"error"、"warning"、"information"、"all"（默认）。取值语义是“显示不低于该严重级别的诊断”："error" 只显示错误，"warning" 显示错误与警告，"information" 再包含信息级，"all" 则显示全部。该枚举（ScrollbarDiagnostics）定义在 crates/settings_content/src/editor.rs 中，并标注了各变体的展示范围。

悬停提示与诊断间跳转

除了被动查看，Zed 还提供更主动的交互方式：

• 悬停（Hover）：将光标悬停在诊断上，会弹出一个渲染了完整诊断信息的 tooltip；
• editor::GoToDiagnostic / editor::GoToPreviousDiagnostic：在文件内的诊断之间向后/向前跳转，并为当前激活的诊断显示一个 popover。

这两个动作的定义见 crates/editor/src/actions.rs：

/// Expands the diagnostic under the cursor, if any, in case diagnostics are not
/// yet active. Otherwise, goes to the next diagnostic in the file.
#[derive(PartialEq, Clone, Default, Debug, Deserialize, JsonSchema, Action)]
#[action(namespace = editor)]
#[serde(deny_unknown_fields)]
pub struct GoToDiagnostic {
    #[serde(default)]
    pub severity: GoToDiagnosticSeverityFilter,
}

两个动作结构都携带一个可选的 severity 过滤字段（GoToDiagnosticSeverityFilter，定义于 crates/project/src/project_settings.rs），因此可以在命令面板中按严重级别精确跳转到下一处/上一处诊断。编辑器菜单中还提供了 ToggleDiagnostics 动作用于切换诊断面板，同样可见于 crates/editor/src/actions.rs。

内联诊断（Error lens）：把错误显示在代码右侧

Zed 支持把诊断以“lens”（透镜）的形式显示在代码行的右侧，即通常所说的 Error lens。该功能默认关闭，有两种开启方式：

1. 通过编辑器菜单临时开启或关闭；
2. 通过设置永久开启：

"diagnostics": {
  "inline": {
    "enabled": true,
    "max_severity": null
  }
}

其中 max_severity 的取值与编辑器设置 diagnostics_max_severity 相同；设为 null 时继承编辑器的 diagnostics_max_severity 设置（这一点在 assets/settings/default.json 的注释中有明确说明）。

除了文档中提到的这两个字段，diagnostics.inline 块还包含三个控制展示节奏与布局的参数，均可在 assets/settings/default.json 中查到：

参数	默认值	作用
enabled	false	是否内联显示诊断
update_debounce_ms	150	最后一次诊断更新之后，延迟多少毫秒再渲染内联诊断，用于避免编辑过程中的闪烁
padding	4	源码行末尾与内联诊断之间的间距（以 em 宽度为单位）
min_column	0	内联诊断的最小起始列，可用来水平对齐；超过该列的长行仍会把诊断推到更右的位置
max_severity	null	内联诊断的最低显示严重级别，null 时继承编辑器设置

对应参数结构（含 padding、min_column、max_severity）定义在 crates/settings_content/src/project.rs 中，字段注释与默认配置一一对应。

其他界面位置：项目面板与编辑器标签页

项目面板（Project Panel）

项目面板可以按文件内诊断的严重级别给文件条目着色。配置项为：

"project_panel": {
  "show_diagnostics": "all"
}

可能取值为 "off"、"errors"、"all"（默认）。从源码看，实际着色逻辑在 crates/project_panel/src/project_panel.rs 的 update_diagnostics 中：读取各文件的诊断摘要后，只要 error_count > 0 就标记为错误级；当设置为 "all" 且 warning_count > 0 时才标记为警告级；设置为 "off" 时不做任何标记。此外，"project_panel" 块下还有一个配套的 "diagnostic_badges" 设置（默认 false），用于在文件名旁显示错误/警告数量徽标，见 assets/settings/default.json。

编辑器标签页（Editor Tabs）

与项目面板类似，编辑器标签页也可以着色，配置项为：

"tabs": {
  "show_diagnostics": "off"
}

可能取值为 "off"（默认）、"errors"、"all"。注意标签页的默认值与项目面板不同：项目面板默认 "all"，标签页默认 "off"，这一点同样可以从 assets/settings/default.json 中得到印证。

配置总览与默认值

综合 docs/src/diagnostics.md 与 assets/settings/default.json，本主题涉及的全部设置项及其默认值如下：

设置项	取值	默认值	作用域
diagnostics_max_severity	"off" / "error" / "warning" / "info" / "hint" / null	null（显示全部）	编辑器内下划线诊断
scrollbar.diagnostics	"none" / "error" / "warning" / "information" / "all"	"all"	滚动条诊断指示
diagnostics.inline.enabled	true / false	false	内联诊断（Error lens）
diagnostics.inline.max_severity	同 diagnostics_max_severity	null（继承编辑器设置）	内联诊断级别过滤
diagnostics.lsp_pull_diagnostics.enabled	true / false	true	是否主动向 LSP 拉取诊断
diagnostics.lsp_pull_diagnostics.debounce_ms	整数（毫秒）	50	拉取诊断的节流间隔
project_panel.show_diagnostics	"off" / "errors" / "all"	"all"	项目面板条目着色
tabs.show_diagnostics	"off" / "errors" / "all"	"off"	编辑器标签页着色

如果你从 VS Code 迁移而来，项目面板的 show_diagnostics 还会参与迁移映射：crates/settings/src/vscode_import.rs 中读取了 VS Code 的 problems.decorations.enabled 设置来推导该值。

延伸阅读

• 官方文档原文：docs/src/diagnostics.md
• 全部设置项参考：docs/src/reference/all-settings.md
• 完整默认配置示例：assets/settings/default.json
• 编辑器动作定义（GoToDiagnostic、ToggleDiagnostics 等）：crates/editor/src/actions.rs
• 诊断数据结构与测试：crates/diagnostics/src/diagnostics.rs、crates/diagnostics/src/diagnostics_tests.rs