根本原因是工具链路径不一致：CMake编译成功因正确传递-I参数，而VSCode调试（F5）或clangd未读取compile_commands.json或配置缺失；需启用CMAKE_EXPORT_COMPILE_COMMANDS、用target_include_directories()替代全局include_directories()，并禁用冲突的C/C++插件。
VSCode 里 F5 调试失败、clangd 报错、终端编译却正常——根本不是头文件真丢了，而是不同工具链看到的 include 路径不一致。
VSCode 的 CMake Tools 插件没用 CMake 生成的编译参数
你执行 cmake .. && make 成功，是因为 CMake 正确解析了 include_directories(${CMAKE_SOURCE_DIR}/include)，并把 -I/path/to/include 传给了 g++。但 VSCode 默认的调试启动（F5）可能绕过 CMake 编译流程，直接调用 g++ main.cpp -o output/main，压根没加 -I 参数。
- 检查
.vscode/launch.json：如果里面用了"preLaunchTask": "build"，确保对应tasks.json真的执行了ninja或make，而不是硬编码调用g++ - 更稳妥的做法是启用
compile_commands.json：在CMakeLists.txt开头加set(CMAKE_EXPORT_COMPILE_COMMANDS ON)，再用 CMake Tools 重新 Configure，VSCode 就能自动读取真实编译参数 - 别信“CMake 配置成功就万事大吉”——CMake Tools 的
configure和build是两个独立动作，缺一不可
clangd 在 Windows 上找不到头文件的常见原因
clangd 不读 CMakeCache.txt，也不自动解析 include_directories()，它只认自己配置的 -I 路径或 compile_commands.json。
- 优先生成
compile_commands.json：CMake Tools 启用后，按Ctrl+Shift+P→ “CMake: Edit User-Local CMake Kits”，确认 kit 选对，再执行 “CMake: Configure” 即可生成 - 若不想依赖 JSON 文件，可在项目根目录建
.clangd，内容写成：CompileFlags: Add: [-I"./include", -I"./src"]
（路径用正斜杠，${workspaceFolder}在 Windows 上有时不展开） - 注意：VSCode 的 C/C++ 插件（ms-vscode.cpptools）和 clangd 冲突，禁用前者，只留 clangd
Windows 下 include 路径写法容易踩的坑
Windows 路径分隔符是反斜杠 \，但 C++ 的 #include 里写 "include\Gun.h" 是合法的；问题出在 CMake 变量拼接时。
-
include_directories(${CMAKE_SOURCE_DIR}\include)❌：反斜杠会被当转义符，导致路径变成C:/projectinclude（丢了个/） - 必须写成
include_directories("${CMAKE_SOURCE_DIR}/include")✅：用正斜杠或双引号包裹，CMake 自动转义 - 头文件引用尽量用双引号
"Gun.h"而非尖括号<Gun.h>：前者优先查当前目录和-I路径，后者只查系统路径，容易漏掉本地头文件
最常被忽略的一点：CMake 的 include_directories() 是全局作用域，而 target_include_directories() 才真正绑定到具体 target。如果你的项目有多个 executable 或 library，用后者才能保证每个 target 拿到正确的头文件路径，且不会污染其他 target。
