VSCode中仅用clang-tidy处理非CMake项目时外部头文件找不到的问题

云上老周

2026-6-16

解决clang-tidy无法找到外部头文件的方案

1. 修正命令行参数传递方式

你使用-- -IFOLDER_PATH传递编译参数时，需注意以下细节：

FOLDER_PATH必须是头文件所在的绝对路径，或相对于当前执行clang-tidy命令的相对路径（比如头文件位于../external/include，参数应写为-I../external/include）
多路径需逐个用-I指定，例如-- -Ipath1 -Ipath2
确保在项目根目录下执行命令，避免相对路径错位

2. 在.clang-tidy配置文件中嵌入包含路径

直接在.clang-tidy里添加编译选项配置，无需每次命令行重复输入：

Checks:          cppcoreguidelines-*
WarningsAsErrors: true
FormatStyle:     google
CompileFlags:
  Add: [-I/绝对路径/到/头文件目录, -I相对路径/到/另一头文件目录]

clang-tidy会自动读取该配置中的编译参数。

3. 配置VSCode的clangd插件参数

由于你启用了clangd，需在.vscode/settings.json中添加clangd的编译参数：

{
  "clangd.arguments": [
    "-I/绝对路径/到/头文件目录",
    "-I相对路径/到/另一头文件目录"
  ]
}

若没有settings.json，可直接在VSCode设置中搜索clangd arguments，手动添加上述参数。

4. 手动生成compile_commands.json（长期推荐方案）

即使不使用CMake，也可手动创建compile_commands.json放在项目根目录，clang-tidy和clangd会自动读取其中的编译配置：

[
  {
    "directory": "/你的项目根目录绝对路径",
    "command": "gcc -c file.c -I/头文件目录绝对路径",
    "file": "file.c"
  },
  {
    "directory": "/你的项目根目录绝对路径",
    "command": "gcc -c another_file.c -I/头文件目录绝对路径",
    "file": "another_file.c"
  }
]

每个条目对应一个源文件，command字段需包含正确的编译参数。