先确认Boost真实存在且路径正确：设BOOST_ROOT指向根目录，或用Boost_DIR/CMAKE_PREFIX_PATH指向含BoostConfig.cmake的路径；组件名须小写且已编译；启用-DBoost_DEBUG=ON查看实际搜索过程。
find_package(Boost) 找不到 Boost 怎么办？先确认它真在那儿
直接给 find_package(Boost) 加路径不是靠传参，而是靠告诉 CMake “去哪找配置文件”。Boost 官方不自带 BoostConfig.cmake（除非你用的是现代打包版或自己构建时启用了 BOOST_BUILD_CONFIG），所以默认走的是模块模式——也就是依赖 CMake 自带的 FindBoost.cmake。这个模块不看 xxx_DIR 变量，而是查 BOOST_ROOT、BOOST_INCLUDEDIR、BOOST_LIBRARYDIR 这几个环境/缓存变量。
-
BOOST_ROOT是最常用也最推荐的：指向 Boost 源码或安装根目录（比如/opt/boost-1.85.0或$HOME/local/boost） -
BOOST_INCLUDEDIR和BOOST_LIBRARYDIR可以更细粒度控制，但容易漏配——比如头文件在include/boost，库在lib64/，就得两个都设对 - 如果用的是 Homebrew（macOS）或 apt（Ubuntu），通常不需要手动指定，CMake 会自动扫
/opt/homebrew/opt/boost或/usr/lib/x86_64-linux-gnu/cmake/boost_*/*Config.cmake
想强制走 Config 模式？得有 BoostConfig.cmake
如果你手头的 Boost 确实提供了 BoostConfig.cmake（常见于通过 vcpkg、conan 或自建 CMake 构建时启用 -DBUILD_BOOST_CMAKE_CONFIG=ON 得到的安装包），那就可以绕过 FindBoost.cmake，走更可靠的配置模式：
- 把 Boost 安装目录（比如
/path/to/boost/install）下包含lib/cmake/boost_xxx/BoostConfig.cmake的完整路径，赋给缓存变量Boost_DIR（注意大小写，是Boost_DIR不是BOOST_DIR） - 或者更通用：把该目录的父级（即
/path/to/boost/install/lib/cmake）加到CMAKE_PREFIX_PATH里，CMake 会自动拼出子路径去搜 - 运行 CMake 时加参数：
cmake -DBoost_DIR=/path/to/boost/install/lib/cmake/boost_xxx ..
组件没找到？检查 COMPONENTS 和实际库名是否对得上
find_package(Boost REQUIRED COMPONENTS system filesystem) 失败，90% 不是因为路径错，而是库名不匹配或没编译对应 .so/.a：
- Boost 组件名是小写的，且不能带
libboost_前缀：写system，别写libboost_system或Boost::system - 确保你安装的 Boost 真编译了这些组件：比如只运行了
./b2 install --with-system，那filesystem就不会被装进去 - Linux 上注意
libboost_filesystem.so.1.85.0这类带版本号的文件是否存在；若只有.so符号链接，某些旧版 CMake 会漏判 - macOS 上若用 Clang + libc++，要确认 Boost 是用相同 STL 编译的，否则链接时报 undefined symbol
调试 find_package 到底在哪儿找？开 VERBOSE
光猜路径不如看 CMake 实际行为。加 -DBoost_DEBUG=ON 或全局 -DCMAKE_FIND_DEBUG_MODE=ON，CMake 会在终端打印每一步搜索路径和失败原因：
find_package(Boost) called with the following arguments: PATHS: /usr/local /opt/homebrew /usr ... NO_MODULE: FALSE → will try FindBoost.cmake first Looking for Boost_ROOT: not set Looking for BOOST_ROOT: /opt/boost-1.85.0 → found! Searching for headers in: /opt/boost-1.85.0/include/boost Searching for libraries in: /opt/boost-1.85.0/lib Found boost_system: /opt/boost-1.85.0/lib/libboost_system.so
真正卡住的地方，往往藏在最后一行“Found”之前那几行里——比如它找到了头文件，但库目录下压根没有 libboost_filesystem，却没报错，只默默跳过该 component。
最容易被忽略的是：Boost 的 FindBoost.cmake 默认只查 lib 和 lib64，如果你把库装到了 lib/x86_64-linux-gnu 这种多层嵌套路径下，它就直接略过了——这时要么改路径，要么显式设 BOOST_LIBRARYDIR。
