Ladybird 浏览器 Helix 编辑器配置指南：让 clangd 与 clang-format 开箱即用

本文基于 Ladybird 仓库中的 Helix 编辑器配置文档 展开，讲清楚在开发 Ladybird 这个大型 C++ 项目时，如何用 Helix 编辑器接入 clangd 语言服务器并正确关闭其自动头文件插入行为，同时配合仓库自带的 .clangd 与 .clang-format 配置文件，使代码补全、诊断和格式化行为与项目 CI 保持一致。读完后，你可以直接复制文档中的完整配置，在 Ladybird 源码树中获得可用的 LSP 开发环境。

为什么 Ladybird 需要专门配置 Helix

Helix 自带对 clangd 和 clang-format 的原生支持：当它检测到 C++ 文件类型时，会自动尝试用 clangd 提供补全、跳转、诊断，用 clang-format 提供格式化。对于小型项目，这套默认行为通常就够了。

但 Ladybird 的代码规模和组织方式使得默认配置会产生两个实际问题：

1. clangd 会自动往文件里插入它认为“缺失”的头文件（#include），这与项目的头文件约定冲突；
2. clangd 需要依赖 CMake 构建生成的编译数据库（compile_commands.json）才能准确解析符号，否则诊断结果大量误报。

因此官方文档给出了一份项目级的 Helix 配置，核心就是让 clangd “只诊断、别动我的头文件”。

核心配置：项目根目录的 .helix/languages.toml

按照 HelixConfiguration.md 的说明，在 Ladybird 项目根目录创建 .helix/languages.toml 文件，内容如下：

[language-server.ladybird]
command = "clangd"
args = ["--header-insertion=never"]

[[language]]
name = "cpp"
language-servers = ["ladybird"]

这份配置分成两段，逐段说明其含义：

定义一个名为 ladybird 的语言服务器

[language-server.ladybird]
command = "clangd"
args = ["--header-insertion=never"]

• command = "clangd"：指定启动命令为 clangd（需要在 PATH 中可执行）。这样命名的服务器别名 ladybird 只是为了与 Helix 内置的默认 clangd 区分开，表明这是 Ladybird 项目定制的参数组合。
• args = ["--header-insertion=never"]：这是整份配置的关键参数。clangd 默认会在你使用某个符号但对应 #include “缺失”时，提示并自动插入头文件；--header-insertion=never 完全禁用这一行为，让 clangd 只做诊断而不改动源码中的头文件列表。

把 C++ 语言绑定到自定义服务器

[[language]]
name = "cpp"
language-servers = ["ladybird"]

这段把 cpp 文件类型的语言服务器指向上面定义的 ladybird，即覆盖 Helix 默认的 clangd 启动参数。两个段落配合起来的效果是：编辑任何 C++ 文件时，启动的是 clangd --header-insertion=never，而不再是默认配置。

为什么必须禁用 header insertion：对照项目的 .clangd

禁用自动插头不只是个人偏好，而是与项目自身的 clangd 约定一致。Ladybird 仓库根目录自带一份 .clangd 配置，clangd 启动后会自动读取它：

CompileFlags:
  CompilationDatabase: Build/release

Diagnostics:
  UnusedIncludes: None
  MissingIncludes: None

Style:
  AngledHeaders: ["AK/.*", "Lib.*"]

其中 Diagnostics.MissingIncludes: None 表示 clangd 不报告“缺少 include”这类诊断，这与 --header-insertion=never 形成一致的策略：项目整体上不接受工具自动增删头文件。而 Style.AngledHeaders 规定了 AK/ 与 Lib* 路径下的头文件应使用尖括号写法，这属于项目头文件风格的一部分。

另外 CompilationDatabase: Build/release 指明了编译数据库位置：clangd 的补全与诊断质量依赖于 CMake 构建时生成的 compile_commands.json。因此使用前需要先构建一次项目（例如通过 BuildInstructionsLadybird.md 介绍的方式执行构建，或像 Neovim 文档 NvimConfiguration.md 中建议的那样先运行 ./Meta/ladybird.py run ladybird 至少一次），否则 Build/release 下没有编译数据库，clangd 只能靠回退标志猜测编译参数，会误报大量 LSP 错误。

格式化端：.clang-format 与 CI 强制的版本

格式化是 Helix 的另一半能力。仓库根目录的 .clang-format 定义了 Ladybird 的格式基线：

BasedOnStyle: WebKit
BreakBeforeBraces: Custom
BraceWrapping:
    AfterFunction: true
IndentPPDirectives: AfterHash
LineEnding: LF
InsertNewlineAtEOF: true
WrapNamespaceBodyWithEmptyLines: Always

整体以 WebKit 风格为基，再叠加函数后换大括号、命名空间体包空行等项目规则；文件末尾还追加了一段 Language: ObjC 规则，覆盖 Objective-C（用于 macOS 相关代码）。Helix 对 C++ 文件做格式化时会自动读取这份配置，无需额外设置。

需要注意的是版本一致性。Meta/Linters/lint_clang_format.py 中定义了 CLANG_FORMAT_MAJOR_VERSION = 21，即 CI 强制使用 clang-format 21，并且会优先查找 clang-format-21 这样带版本后缀的可执行文件。不同大版本的 clang-format 对同一份 .clang-format 可能产出不同结果，所以本地也应安装 21 版本（BuildInstructionsLadybird.md 中展示了从 apt.llvm.org 安装 clang-format-21 等工具链的示例）。如果系统默认 clang-format 版本过低，Helix 格式化出的改动可能与 CI 检查不一致，这一点在 CodingStyle.md 中也有专门强调。

配置完成后的验证与常见问题

配置好之后，可以按以下路径验证环境是否真正可用：

1. 确认 clangd 能拿到编译数据库：先完成一次构建，确认 Build/release 目录下存在 compile_commands.json（对应 .clangd 中的 CompilationDatabase: Build/release）。
2. 打开任意 C++ 文件观察诊断行为：使用一个未 include 的符号时，clangd 应报“未声明的标识符”类错误，但不应弹出/自动插入 #include 建议，这正是 --header-insertion=never 与 MissingIncludes: None 的共同效果。
3. 对文件运行格式化：Helix 会调用 clang-format 并按 .clang-format 规则调整缩进、大括号位置等；若本地 clang-format 不是 21 版本，先升级再格式化，以免与 Meta/Linters/lint_clang_format.py 的 CI 版本要求不一致。

总结来说，Ladybird 的 Helix 配置成本极低——一份十行的 .helix/languages.toml 即可——但它的两个要点（关闭 header insertion、依赖 Build/release 的编译数据库）分别解决了“工具改头文件”和“符号解析不准”这两个大型 C++ 项目中 LSP 环境最常见的坑。仓库内其余编辑器的配置文档（Vim、Neovim、Emacs、VS Code、Qt Creator、CLion、Android Studio）位于 Documentation/EditorConfiguration/ 目录，采用同一套 .clangd / .clang-format 约定，思路可互相参照。