clang之所以会提示找不到 iostream 这类标准头文件，根子上并不在代码本身，而是它默认不会顺手把完整的 C++ 标准库路径一并带上。

换句话说，clang 需要依赖系统里已经装好的 libstdc++ 或 libc++，而且这些路径往往还得手动明确配置。

• Linux 通常要先装 g++
• macOS 需要安装 Command Line Tools 并重新设置 xcode-select
• Windows 则要指定 --target

这些环节只要没配到位，就算代码写得完全没问题，编译时照样会直接报错。

clang 找不到头文件的常见原因

clang 编译单个 .cpp 文件时找不到 iostream 等标准头文件

这不是你代码写错了，而是 clang 默认不自带完整 C++ 标准库头文件路径。

它必须依赖系统已安装的 libc++ 或 libstdc++，而路径没被自动发现。

常见现象：fatal error: 'iostream' file not found、'stdio.h' file not found，但用 g++ 编译同一文件却成功。

• Linux（如 Ubuntu 22.04+）：确认已装 g++ 或 libc++-dev，运行 sudo apt install g++ 最快见效
• macOS：执行 xcode-select --install 补全 Command Line Tools；若用 brew 安装的 llvm，加 -isysroot /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
• Windows（MSYS2）：必须指定 target，例如 clang++ --target=x86_64-w64-mingw32 main.cpp，否则 clang 不知道该用 UCRT 还是 MSVC 的头文件

clang 编译多个源文件时找不到自定义头文件（如 "utils/log.hpp"）

clang 本身不会递归扫描项目结构，#include "xxx" 只在当前目录和你显式指定的路径里找。

CMake 构建成功 ≠ clang 命令行能直接编译。

错误典型表现：单独编译 src/main.cpp 报错说找不到 "utils/log.hpp"，哪怕 include/utils/log.hpp 存在且 CMake 正常链接。

• 最简修复：用 -I 手动加路径，例如 clang++ -I./include src/main.cpp src/utils/log.cpp -o app
• 路径要相对于当前工作目录，不是相对于 .cpp 文件位置；-I./include 比 -I../include 更稳
• 多个头文件目录？叠加写多个 -I，比如 -I./include -I./third_party/rapidjson/include
• 别依赖相对路径跳转（如 #include "../../../include/xxx.h"），既难维护又容易在不同工作目录下失效

编辑器和工具链中的相关问题

clangd 在 VS Code 或 Cursor 中飘红，提示 pp_file_not_found

clangd 是独立进程，不读 CMakeLists.txt，也不继承 shell 环境变量。

它要么靠 compile_commands.json，要么靠配置硬编码路径。

常见误操作：改了 target_include_directories() 就以为 clangd 自动同步——其实完全无关。

• 首选方案：让 CMake 生成 compile_commands.json，加参数 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON，然后在编辑器设置里指向该文件
• 懒人方案：在项目根目录建 .clangd 文件，内容写：

  CompileFlags:
  Add: [-I./include, -I./third_party]

• 全局方案（Windows）：在 %LOCALAPPDATA%clangdconfig.yaml 里配 Add: ["-I${workspaceFolder}/include"]，但注意 .clangd 会覆盖它
• 务必检查 clangd 插件是否用了正确的二进制：VS Code 设置里填对 clangd.path，尤其 MSYS2 用户要指向 ucrt64/bin/clangd.exe，不是随便某个旧版本

clang-tidy 报 clang-diagnostic-error 找不到头文件

clang-tidy 默认当 C 代码处理，即使你传的是 .cpp 文件。

它不自动推断语言，也不读 CMake —— 必须显式告诉它是 C++。

错误输出里有 error: 'vector' file not found [clang-diagnostic-error]，这就是典型信号。

• 关键动作：末尾加 -- -x c++，例如 clang-tidy main.cpp -- -x c++
• 如果还缺第三方头文件，继续追加 -I，如 clang-tidy main.cpp -- -x c++ -I./include -I./deps/gtest/include
• 别漏掉双横线 --：前面是 clang-tidy 参数，后面才是传给底层 clang 的编译参数
• 用 clang-tidy -p build/（指向 build 目录）比手写路径更可靠，前提是 build/compile_commands.json 存在且有效

结论

实际项目里，标准头文件缺失往往暴露工具链配置问题，而自定义头文件找不到基本都是路径没对齐。

clang 系列工具从不“猜”你想要什么路径，所有 -I、-x、--target 都得明说。

这点和 gcc 的宽容完全不同。