CLion中头文件可见性由CMakeLists.txt控制，需用include_directories()或target_include_directories()声明路径，#include ""与搜索逻辑不同，报错时应优先检查路径声明与引用方式是否匹配。
CLion 本身不提供“添加头文件”的图形化按钮，所有头文件的可见性与可包含性，都由 CMake 配置决定。直接在项目目录里放一个 .h 文件，#include "xxx.h" 可能能编译通过，但 #include <xxx.h></xxx.h> 会失败——除非你告诉 CMake 去哪找它。
头文件路径必须写进 CMakeLists.txt 才生效
CMake 是 CLion 的底层构建系统，IDE 界面里看不到“包含路径”设置项，是因为这个逻辑完全交给 CMakeLists.txt 控制。你在文件系统中新建了 include/utils.h，哪怕 CLion 能在项目树里显示它，编译器依然不知道该不该、去哪里搜这个头文件。
-
include_directories()是最常用方式，比如在顶层CMakeLists.txt里加一行：include_directories(${PROJECT_SOURCE_DIR}/include) - 路径必须是 CMake 可识别的：推荐用
${PROJECT_SOURCE_DIR}开头的相对路径，避免硬编码绝对路径（如/home/user/myproj/include），否则换机器就失效 - 多个目录用空格分隔，不是换行或逗号：
include_directories(include src/drivers/inc Drivers/CMSIS/Include) - 如果头文件在子模块里（比如
drivers/stm32_hal/Inc），且该模块有自己的CMakeLists.txt，优先用target_include_directories()绑定到具体 target，比全局include_directories()更安全
什么时候用 #include "xxx.h"，什么时候用 #include <xxx.h></xxx.h>
这取决于你如何组织和声明路径，不是 IDE 决定的，而是 C++ 预处理器规则：
-
#include "xxx.h"：先在当前源文件所在目录找，再按-I（即include_directories）路径顺序查找。适合项目内头文件，比如#include "config.h"放在同级目录时 -
#include <xxx.h></xxx.h>：跳过当前目录，只查-I路径。适合统一管理的公共头文件，比如你把所有头放在include/下，并用include_directories(${PROJECT_SOURCE_DIR}/include)声明，那就可以写#include <utils></utils> - 混用容易出错：比如你用
include_directories(include)，却写#include "utils/string_utils.h"，而实际路径是include/utils/string_utils.h——这时预处理器会在源文件目录下找utils/string_utils.h，找不到就报错
常见报错和对应检查点
看到 “No such file or directory” 不要急着改 include 写法，先定位是路径没声明、声明错了，还是引用方式不匹配：
-
Fatal error: 'my_header.h' file not found：确认my_header.h所在目录是否已加入include_directories()；再确认你写的是"my_header.h"还是<my_header.h></my_header.h>，二者搜索逻辑不同 - CLion 编辑器里有红色波浪线，但编译通过：这是 CLion 的索引没更新，点菜单
File → Reload CMake Project或点击右上角的闪电图标刷新 CMake 缓存 - 新增头文件后，旧代码突然报 “undefined reference”：说明头文件里声明了函数，但对应实现（
.cpp）没加进 CMake target，检查add_executable()或add_library()的源文件列表是否漏了xxx.cpp - 用了第三方库（如 spdlog、fmt），头文件在
/usr/local/include，但 CLion 提示找不到：Linux/macOS 下可以加include_directories(/usr/local/include)；Windows 下若用 vcpkg，更推荐用find_package(fmt CONFIG)+target_link_libraries()，避免硬编码路径
真正卡住人的往往不是语法，而是 CMake 缓存没刷新、路径拼错一个斜杠、或者误以为 CLion 界面操作能替代 CMake 声明。只要记住：CLion 显示文件 ≠ 编译器知道它存在，中间差的那层，就是 CMakeLists.txt 里白纸黑字写的路径和目标定义。
