本文适用于在 Linux 双系统中使用本机 VS Code 开发 ROS 2/C++ 项目。

版本提醒：下面示例使用 23.1.0。如果你下载的是其他版本，请把命令和配置中的 23.1.0、23 等版本号改成你实际下载的版本。

1. 下载 clangd

打开 clangd 官方发布页面：

https://github.com/llvm/llvm-project/releases

下载 Linux 版本，例如：

clangd-linux-23.1.0.zip

普通本地开发只需要下载 clangd-linux-版本号.zip。clangd_indexing_tools 是集中式索引工具，一般不需要。

2. 解压安装

在工作区根目录打开终端：

unzip -q clangd-linux-23.1.0.zip -d /tmp
sudo install -Dm755 /tmp/clangd_23.1.0/bin/clangd /usr/local/bin/clangd
sudo cp -a /tmp/clangd_23.1.0/lib/clang /usr/local/lib/

如果下载的不是 23.1.0，请把压缩包名称和 /tmp/clangd_23.1.0 中的版本号改成实际版本号。

检查版本：

/usr/local/bin/clangd --version

这里把 clangd 主程序直接安装为 /usr/local/bin/clangd。同时复制 lib/clang 是因为 clangd 需要其中的内置头文件和资源文件。

使用 /usr/local/bin 不会覆盖 /usr/bin 中由系统包管理器维护的文件。

终端命令中可以使用 ~ 表示用户主目录，但 VS Code 的 JSON 配置不一定展开 ~，因此配置中使用绝对路径 /usr/local/bin/clangd。

3. 安装 VS Code 扩展

在 VS Code 扩展市场安装：

clangd

选择发布者为 LLVM 的扩展：

llvm-vs-code-extensions.vscode-clangd

建议关闭 Microsoft C/C++ 扩展的 IntelliSense，避免和 clangd 冲突。

4. 配置 VS Code

打开 VS Code 的用户设置：

Ctrl+Shift+P → Preferences: Open User Settings (JSON)

也可以直接编辑配置文件：

~/.config/Code/User/settings.json

加入下面配置：

{
    "clangd.path": "/usr/local/bin/clangd",
    "clangd.arguments": [
        "--background-index",
        "--compile-commands-dir=${workspaceFolder}",
        "--completion-style=detailed",
        "--header-insertion=iwyu",
        "--query-driver=/usr/bin/g++*",
        "--clang-tidy",
        "-j=12"
    ],
    "clangd.trace": "verbose",
    "clangd.fileStatus": true,
    "C_Cpp.autocomplete": "disabled",
    "C_Cpp.intelliSenseEngine": "disabled"
}

再次提醒：如果安装的是其他版本，请把解压目录中的 23.1.0 改成实际版本号。clangd.path 固定使用 /usr/local/bin/clangd，不需要写版本号。

不要把 --compile-commands-dir 写进 clangd.fallbackFlags，也不要加入 Windows 参数，例如：

-DWIN32
-DUNICODE
-I${env:INCLUDE}

5. 重启并检查

在 VS Code 执行：

Ctrl+Shift+P → Developer: Reload Window
Ctrl+Shift+P → clangd: Restart language server

完成后，clangd 就可以提供：

• C++ 代码补全
• 函数和变量跳转
• 头文件检查
• 编译错误诊断
• clang-tidy 静态检查
• 后台索引

6. 如果仍然找不到 iostream 等标准库

如果 clangd 仍然提示找不到：

#include <iostream>

或者其他 C++ 标准库头文件，可以尝试重新安装 GCC 对应的标准库开发文件：

sudo apt install libstdc++-12-dev

然后检查系统中是否存在对应头文件：

ls /usr/include/c++/

正常情况下可以看到类似：

12

如果你的 GCC 版本不是 12，例如：

g++ --version

显示的是 GCC 13，那么更建议安装对应版本：

sudo apt install libstdc++-13-dev

7. 检查 CMakeLists.txt

对于 ROS 2 / C++ 项目，建议在 CMakeLists.txt 中明确指定 C++ 标准：

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

对于 ROS 2 项目，一般使用 C++17 就足够了。

修改完成后，重新编译项目。

例如 ROS 2 工作区：

colcon build --symlink-install

然后重新生成 compile_commands.json。

如果项目使用 CMake，可以加入：

set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

或者构建时：

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..

clangd 会根据 compile_commands.json 获取：

• 头文件搜索路径
• 编译参数
• 宏定义
• C++ 标准
• ROS 2 依赖路径

因此对于 ROS 2 项目来说，compile_commands.json 非常重要。

8. 最后重启 VS Code

修改完成后执行：

Ctrl+Shift+P → Developer: Reload Window

然后：

Ctrl+Shift+P → clangd: Restart language server

如果配置正确，此时类似：

#include <iostream>
#include <memory>
#include <vector>

#include <rclcpp/rclcpp.hpp>

这些头文件应该都能够正常识别，代码补全、跳转和错误提示也会恢复正常。