Clang提示找不到头文件的根本原因是工具未获取正确搜索路径，需通过compile_commands.json或--query-driver指定编译器、用target_include_directories声明路径、clang-tidy加-x c++和-I参数统一上下文。
Clang 提示找不到头文件，绝大多数情况下不是代码写错了，而是 Clang 没拿到正确的头文件搜索路径——它编译能过，但编辑器/静态分析工具（如 clangd、clang-tidy）找不到 iostream 或你自己的 myheader.h，本质是上下文缺失。
clangd 找不到系统头文件（如 iostream、stdio.h）
这是最常见也最容易误判的问题：项目用 g++ 编译完全正常，但 VSCode 里 clangd 红线一片。根本原因是 clangd 启动时没继承 GCC 的 include 路径，也没读到你的编译参数。
- 先确认 clangd 是否指向了和你编译器配套的版本：比如你在 MSYS2 的
ucrt64环境下用clang++，那 clangd 也得从ucrt64/bin/clangd.exe启动，否则它会按默认逻辑找系统头，而找不到 MSYS2 的/ucrt64/include/c++/v1/ - 必须生成
compile_commands.json：CMake 项目加-DCMAKE_EXPORT_COMPILE_COMMANDS=ON，然后运行cmake .. && ninja；该文件会告诉 clangd 每个源文件实际用什么参数编译，包括所有-I和--target - 如果不想生成 compile_commands.json，可在 VSCode 的
settings.json中强制 clangd 使用你的编译器驱动："clangd.arguments": ["--query-driver=/path/to/clang++"]，路径必须精确到可执行文件，且该 clang++ 需能正常输出-v信息
clangd 找不到自定义头文件（如 #include "utils/log.h"）
这类报错往往出现在跨目录包含时，比如 src/main.cpp 包含 include/utils/log.h，但 clangd 不知道 include/ 是头文件根目录。
- 不要靠硬写
#include "../../../include/utils/log.h"来绕过——这会让 clangd 更难推导，也破坏可维护性 - CMake 项目必须用
target_include_directories(your_target PRIVATE "${CMAKE_SOURCE_DIR}/include")显式声明，且确保该命令在add_executable()或add_library()之后 - 如果用了
compile_commands.json，检查里面对应源文件的 command 字段是否真包含了-I/path/to/your/include；没有就说明 CMake 配置没生效 - Qt 项目额外注意：
.pro文件里要写INCLUDEPATH += $$PWD/include，且$$PWD是 .pro 所在目录，不是 src 或 build 目录
clang-tidy 或命令行 clang++ 报 file not found
clang-tidy 默认不读 CMake 配置，也不自动复用 clangd 的设置，它需要你手动喂参数。
- 必须显式指定语言模式：
clang-tidy test.cpp -- -x c++，否则它可能当 C 文件处理，找不到 C++ 标准库 - 加
-I路径时，多个路径用多个-I，不能合并：-I include -I thirdparty/openssl/include，顺序影响优先级 - 交叉编译场景下，
--target必须匹配你实际使用的工具链，比如--target=x86_64-w64-mingw32，否则 clang 会去查 Linux 路径，自然找不到 Windows 头文件 - macOS 上尤其容易踩坑：系统 Clang 依赖 Xcode SDK，Homebrew 安装的 LLVM 默认不带 SDK 路径，得加
-isysroot $(xcrun --show-sdk-path)
真正麻烦的从来不是“怎么加路径”，而是路径来源不一致：CMake 用一套，clangd 用另一套，clang-tidy 又自己猜一套。统一靠 compile_commands.json 是最省心的做法，但它要求构建系统支持且每次修改 CMakeLists.txt 后要重生成——这点很容易被忽略。
