优先使用 target_include_directories 而非 include_directories，因其作用域明确、支持 PUBLIC/PRIVATE/INTERFACE 权限控制，避免全局污染和头文件冲突；需配合 find_path 查找第三方头文件路径，静态库链接时必须单独配置头文件路径，且头文件与库路径须分别处理。
优先用 target_include_directories，别用 include_directories —— 后者是全局污染，容易引发头文件冲突或误包含。
为什么 target_include_directories 是首选
它把头文件路径绑定到具体目标（比如可执行文件或库），作用域清晰，支持 PUBLIC/PRIVATE/INTERFACE 权限控制。比如你写一个库，想让使用者也能看到它的头文件，就用 PUBLIC；如果只是内部实现用的头，就用 PRIVATE。
而 include_directories 会把路径加到所有后续目标里，哪怕某个目标根本不需要这些头文件，也会被编译器搜索，可能掩盖路径错误、引入意外依赖。
常见错误现象：#include "xxx.h" 编译通过，但换一台机器或改个 target 就报 file not found —— 很可能就是靠全局 include_directories “蒙混过关”了。
-
target_include_directories(my_target PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)：仅my_target能用 -
target_include_directories(my_lib PUBLIC $<include>)</include>：安装后供下游项目使用 - 路径推荐用
${CMAKE_CURRENT_SOURCE_DIR}或${PROJECT_SOURCE_DIR}，避免硬编码相对路径
find_path 查第三方头文件目录时的坑
直接写 include_directories(/opt/env/boost/include) 看似快，但不可移植。正确做法是用 find_path 动态定位，失败时能明确报错，而不是等到编译才崩。
典型场景：你在 /opt/env 下装了 Boost，但别人可能装在 /usr/local 或用 conda 管理。
- 先调用
find_path(BOOST_INCLUDE_DIR NAMES boost/version.hpp HINTS /opt/env/boost/include PATHS /usr/include /usr/local/include) - 检查结果：
if(NOT BOOST_INCLUDE_DIR)就message(FATAL_ERROR "Boost headers not found") - 再传给
target_include_directories(my_target PRIVATE ${BOOST_INCLUDE_DIR}) - 注意：
find_path不会自动 fallback 到系统默认路径，PATHS要显式列全，或用NO_DEFAULT_PATH控制行为
链接静态库时头文件路径必须单独配
静态库（.a）本身不带头文件信息，target_link_libraries 只负责链接符号，不解决 #include。很多人以为“链上了就万事大吉”，结果编译卡在第一行 #include。
典型错误：用 find_library 找到 libyaml-cpp.a，然后只写 target_link_libraries(app PRIVATE yaml-cpp) —— 编译器根本不知道去哪找 yaml-cpp/node.h。
- 必须配合
find_path找头文件目录，或手动指定：target_include_directories(app PRIVATE /opt/env/yaml-cpp/include) - 如果静态库是自己构建的，建议在它的
CMakeLists.txt里用target_include_directories(mylib PUBLIC $<include>)</include>，这样下游target_link_libraries时自动继承头路径 - 别依赖
link_directories—— 它只影响链接器找.so/.a，对预处理阶段的头文件搜索完全无效
跨平台路径拼接别手写斜杠
Windows 用 ，Linux/macOS 用 /，硬拼 "include/boost" 没问题，但拼绝对路径或变量组合时容易翻车。
比如 ${THIRD_PARTY_ROOT}/include 在 Windows 上可能变成 C:optenvinclude，但 CMake 内部路径处理期望 POSIX 风格。
- 统一用
file(TO_CMAKE_PATH "${THIRD_PARTY_ROOT}" THIRD_PARTY_CMAKE_PATH)转换路径分隔符 - 或者直接用
list(APPEND INCLUDE_DIRS "${THIRD_PARTY_ROOT}/include")，CMake 会自动 normalize - 避免
string(REPLACE "\" "/" ...)这类手工替换，不可靠且难维护
最常被忽略的是：头文件路径和库路径是两件事，必须分别配置；target_include_directories 的权限修饰符不是可选项，它直接决定下游能否正确包含你的头文件。
