根本原因是CMake未向编译器、IDE IntelliSense及下游依赖目标正确传递头文件路径；include_directories仅作用于当前作用域且不传递依赖，而target_include_directories可精准控制作用域与传递性。
编译能过但编辑器报红、F5调试失败、下游包引用时报 fatal error: xxx.h: No such file or directory——这些问题本质不是“头文件丢了”，而是 CMake 没把路径正确告诉三类不同角色：编译器、IDE 的 IntelliSense、以及下游依赖目标。
include_directories() 为什么有时无效？
它只影响当前 add_executable() 或 add_library() 的编译阶段，且不传递给依赖它的其他 target。常见失效场景：
- 你在顶层
CMakeLists.txt里写了include_directories(${CMAKE_SOURCE_DIR}/include)，但子目录的add_library()在另一个CMakeLists.txt里定义，没继承该设置 - 你用
find_package()找第三方库，却没用target_include_directories(your_target PRIVATE|PUBLIC|INTERFACE ...)把头路径绑定到具体 target 上 - 你在 Android 或 ROS 2 中构建动态库，但没用
INSTALL_INTERFACE告诉安装后头文件该放哪
VS Code / CLion 编辑器报红但编译成功
这是典型 IDE 和构建系统脱节。CMake Tools 插件可能没刷新 compile_commands.json，或 C/C++ 插件没读取到正确路径。
- 执行
CMake: Delete Cache and Reconfigure（CLion 是Reload project），强制重生成compile_commands.json - 检查
c_cpp_properties.json中的includePath是否包含${workspaceFolder}/build/compile_commands.json对应的路径，或直接硬编码如"${workspaceFolder}/include" - 确认 VS Code 左下角显示的配置名称（如 “GCC”）与你实际使用的编译器一致；否则 IntelliSense 会按错误规则解析
ROS 2 / Android / ESP-IDF 等平台特有问题
这些平台要求头路径必须显式导出，不能只靠 include_directories()。
- ROS 2 中，若你的包提供头文件给下游用，必须在
target_include_directories()里用INSTALL_INTERFACE：target_include_directories(my_lib PUBLIC $<include>)</include> - Android NDK 下，
set_target_properties()配PUBLIC_HEADER只影响安装行为，真正编译时仍需target_include_directories(mylib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include) - ESP-IDF 要求每个组件在自己目录下的
CMakeLists.txt中声明COMPONENT_ADD_INCLUDEDIRS，而不是在项目根目录统一配
头文件在 IDE 里不显示（Qt Creator / Visual Studio）
这只是 IDE 项目视图问题，不影响编译，但影响开发效率。
- 把头文件加进
add_executable()或add_library()的源文件列表里：add_executable(app main.cpp include/myheader.h) - 用
file(GLOB_RECURSE HEADER_FILES "${CMAKE_SOURCE_DIR}/include/*.h")收集，再传给 target - Visual Studio 还需配合
source_group("Header Files" FILES ${HEADER_FILES})才能在解决方案资源管理器中归类显示
最易被忽略的一点：CMake 不会自动 re-run 当你新增一个头文件，除非你改了 CMakeLists.txt 或手动触发 reload。GLOB 方式收集头文件看似省事，反而容易卡在缓存里——编辑器找不到、编译器也漏掉新头文件，直到你删 build 目录重来。
