如何禁用clangd自动添加头文件绝对路径的行为？

问题背景 #

在VSCode中使用clangd自动补全缺失头文件时，工具会插入绝对路径（如#include "/home/user/path/to/Header.h"），而非仅头文件名（#include "Header.h"），导致跨Linux和Termux编译时因路径差异报错。

最小复现示例 #

目录结构 #

./
- .clangd
- compile_commands.json
- bin/
- build/
- include/
--- Header.h
--- Subheader.h
- src/
--- main.cpp

文件内容 #

.clangd

Diagnostics:
  UnusedIncludes: Strict
  MissingIncludes: Strict

Subheader.h

#ifndef IG20240815185417
#define IG20240815185417

struct Subheader {
    int i{2};
};

#endif

Header.h

#ifndef IG20240520170135
#define IG20240520170135
    
#include "Subheader.h"
    
struct Header {
  Subheader sh{};
};

#endif

main.cpp

#include "Header.h"

int main() {
  Header h{};
  Subheader sh{};
  return 0;
}

编译命令与compile_commands.json #

生成compile_commands.json的命令：

clang++ -o build/main.o -c src/main.cpp -MJ build/main.o.json -I./include && clang++ -o bin/main.exe build/main.o && sed -e '1s/^/[\n/' -e '$s/,$/\n]/' build/*.o.json > compile_commands.json

手动生成的compile_commands.json内容：

[
{ "directory": "/ABSOLUTE/PATH/TO/WORKING/DIRECTORY", "file": "src/main.cpp", "output": "build/main.o", "arguments": ["/usr/bin/clang++", "-xc++", "src/main.cpp", "-o", "build/main.o", "--driver-mode=g++", "-c", "-I", "./include", "--target=x86_64-pc-linux-gnu"]}
]

现象 #

main.cpp中Subheader下出现蓝色波浪线，提示缺失直接包含的头文件；选择快速修复后，clangd插入绝对路径的#include "/path/to/working/directory/include/Subheader.h"。

解决方法 #

修改项目根目录下的.clangd配置文件，添加IncludeInsertion相关配置，强制clangd仅插入头文件名：

Diagnostics:
  UnusedIncludes: Strict
  MissingIncludes: Strict
IncludeInsertion:
  Style: "NeverIncludePaths"

配置说明 #

• Style: "NeverIncludePaths"：直接禁用插入路径，仅输出头文件名，完全适配跨系统编译的路径一致性需求。

修改配置后重启VSCode或重新加载clangd服务，再次使用快速修复添加头文件时，就会生成#include "Subheader.h"这类无路径的指令，避免跨系统路径差异问题。

内容的提问来源于stack exchange，提问作者SinixND