find_package找不到包时必须开启调试日志定位问题：cmake 3.17+用-dcmake_find_debug_mode=on，旧版本用-dcmake_find_package_debug=on；检查cmake_prefix_path路径格式、层级结构及是否匹配config/module模式，并注意系统路径优先导致的覆盖问题。
find_package 为什么找不到包？先开调试日志看它到底搜了哪些路径
默认情况下 find_package 完全静默，找不到包时只报错 Could not find XXX，根本不知道它查过哪些目录、是否跳过了你指定的路径。开启调试日志是定位问题的第一步，不是可选动作，是必须做的。
核心方法是加 -DCMAKE_FIND_DEBUG_MODE=ON 启动 CMake 配置阶段：
cmake -DCMAKE_FIND_DEBUG_MODE=ON -DCMAKE_PREFIX_PATH=/your/custom/path ..
注意：这个选项只在 CMake 3.17+ 生效；旧版本用 -DCMAKE_FIND_PACKAGE_DEBUG=ON（CMake 3.2–3.16），但输出信息更少，且不保证打印你传入的 CMAKE_PREFIX_PATH 值。
CMAKE_PREFIX_PATH 指定后没生效？检查路径格式和层级结构
CMAKE_PREFIX_PATH 是一个路径列表，CMake 会按顺序拼接子目录（如 lib/cmake/XXX、share/cmake/XXX）去查找 XXXConfig.cmake 或 FindXXX.cmake。常见失效原因：
- 路径末尾带斜杠（如
/opt/mylib/）会导致拼接出错，应写成/opt/mylib - 你指定的路径下没有符合 CMake 查找规则的结构，比如只有
include/和lib/，但缺lib/cmake/mylib/mylibConfig.cmake - 用了
find_package(XXX REQUIRED)却没配CMAKE_MODULE_PATH，而包只提供了FindXXX.cmake（非 Config 模式），此时CMAKE_PREFIX_PATH不起作用
find_package 的 NO_MODULE / CONFIG 模式差异直接影响日志内容
日志里会明确标出当前走的是 Config 模式还是 Module 模式。区别很关键：
- 加
CONFIG（如find_package(Boost CONFIG REQUIRED)）：只查*Config.cmake，依赖CMAKE_PREFIX_PATH和CMAKE_CONFIG_PATH - 不加
CONFIG或加NO_MODULE：优先查FindXXX.cmake，走CMAKE_MODULE_PATH，此时CMAKE_PREFIX_PATH对查找行为无影响 - 调试日志中看到 “Searching for XXXConfig.cmake” 却没提你的路径？说明它根本没把
CMAKE_PREFIX_PATH加进搜索队列——大概率是你没用CONFIG模式，或 CMake 版本太低不识别该变量
自定义路径下有 Config 文件，但被系统路径覆盖了？
CMake 默认会把系统路径（如 /usr/lib/cmake/）放在搜索队列最前面，哪怕你设置了 CMAKE_PREFIX_PATH，它也只插在中间。结果就是：系统装了个旧版 Boost，你的新版在 /opt/boost，但 CMake 先找到旧版就停了。
解决办法只有两个：
- 用
CMAKE_PREFIX_PATH时，把自定义路径放最前面：-DCMAKE_PREFIX_PATH="/opt/boost;/usr" - 彻底屏蔽系统路径：加
-DCMAKE_IGNORE_PATH="/usr;/usr/local"（CMake 3.15+），但要小心漏掉真正需要的依赖
调试日志里会逐行打印 “Looking for XXXConfig.cmake in …”，顺序一目了然。别猜，直接看它搜的顺序。
