代码自动提示：clangd 与 VS Code 入门

clangd 是基于 Clang 的 C/C++ 语言服务器，负责补全、跳转、诊断和重构；它不会替代 GCC 或 Clang 的工程构建。想让编辑器理解代码，先给它真实编译参数，再调补全选项，这是我更推荐的顺序。clangd 官方入门

先准备可用的编译数据库

安装 clangd 和 VS Code 的 llvm-vs-code-extensions.vscode-clangd 扩展，确认终端能找到程序：

clangd --version

不要照抄旧教程中的 clangd-12 路径，填本机实际安装位置。CMake 工程可在配置时启用 CMAKE_EXPORT_COMPILE_COMMANDS；Bazel 工程可使用 Hedron extractor，但 WORKSPACE/Bzlmod 接入应以该仓库当前说明及项目版本为准。CMake 生成方式、Hedron 上游说明

VS Code 保留一份最小配置

在工程 .vscode/settings.json 中配置：

{
  "clangd.path": "clangd",
  "clangd.arguments": ["--background-index", "--clang-tidy"],
  "C_Cpp.intelliSenseEngine": "disabled"
}

最后一项只在同时安装 Microsoft C/C++ 扩展时需要，用来避免两个语言服务重复提供诊断；它不禁用调试器。复杂参数先不加，旧版本命令行选项可能已经变化，先通过 clangd --help 核对。VS Code 扩展官方说明

clangd 会搜索源码所在目录及父目录的数据库，常规 build/ 目录也会被考虑。如果数据库在其他目录，可以在工程根目录放 .clangd：

CompileFlags:
  CompilationDatabase: build

该相对路径相对于这份 .clangd 文件的位置解析。使用远程开发时，clangd、数据库和工具链路径都要在远端成立。clangd 配置文档

用一次命令把问题缩小

clangd --check=src/main.cpp --compile-commands-dir=build --log=verbose

我会按日志里的实际命令排查，而不是反复重启编辑器：

现象	优先检查
日志是 `Generic fallback command`	数据库目录、当前源码的记录以及 `file` 路径
只有项目头文件找不到	`-I` 目录是否存在，生成头文件是否已构建，数据库是否来自另一台机器
`iostream` 等系统头文件找不到	编译器绝对路径、目标平台、SDK/sysroot，clangd 使用的工具链是否一致
`#ifdef` 分支与构建不一致	当前记录的 `-D` / `-U` 和所选构建配置
头文件跳转结果异常	查看它借用了哪个源文件的命令，再确认包含关系和配置

如果自定义 GCC 交叉工具链能编译，而 clangd 仍找不到系统头，可以给 clangd.arguments 加上针对实际可信编译器的 --query-driver=/opt/toolchain/bin/aarch64-linux-gnu-g++。它允许 clangd 执行数据库中的匹配编译器，以查询系统头路径；这个参数不会替你安装工具链，也不是随便填一个路径就能修好。系统头文件与 query-driver

本次用 macOS 自带 clangd 检查了带 -DAPP_DEBUG=1 的最小数据库，实际日志选中了 CDB 并报告 0 errors。这验证了数据库到解析器这条链路，VS Code UI 和大型 Bazel 工程仍需按自己的环境核对。

想先了解每个参数代表什么，回到 compile_commands.json 科普；想找一个可以直接编译的练习，试试 weak_ptr 生命周期示例。这些文章也收在 C++ 与工具链导读。