报错是因为CMake未在XXX_DIR指定路径下找到XXXConfig.cmake，故忽略该变量并回退至Module模式查找，失败后报错；需确认路径下存在匹配的Config文件或改用FindXXX.cmake。
直接给结论：报错不是因为路径写错了，而是 CMake 没按你预期的模式去查 —— 你设了 XXX_DIR，但它没找到 XXXConfig.cmake，于是放弃该路径、回退到 Module 模式重找，结果又没找到 FindXXX.cmake，最终报错。
为什么 set(XXX_DIR ...) 后还是报 Could NOT find XXX？
这是最典型的“以为设了路径就万事大吉”陷阱。CMake 对 XXX_DIR 的处理非常严格：
- 它只在 Config 模式下使用
XXX_DIR，且必须在该目录（或其子目录lib/cmake/xxx/、share/cmake/xxx/等）里找到XXXConfig.cmake或xxx-config.cmake才算成功 - 如果
XXX_DIR路径下压根没有 Config 文件，CMake 会直接忽略这个变量，转头去走 Module 模式（查CMAKE_MODULE_PATH），再失败才报错 - Windows 下尤其常见：Qt 安装目录里是
Qt5\lib\cmake\Qt5\Qt5Config.cmake，但你设的Qt5_DIR如果指向Qt5\根目录，而没指向Qt5\lib\cmake\Qt5\，它就找不到
怎么确认你设的 XXX_DIR 是对的？
别猜，直接进目录看文件是否存在：
- 打开你设的
XXX_DIR路径，手动搜索*Config.cmake或*-config.cmake - 如果没找到，说明库本身不提供 Config 模式支持（比如老版本 OpenCV 2.x、某些自编译库），那
XXX_DIR就无效，得换路子 - 如果找到了，但名字是
opencv4-config.cmake，而你find_package(OpenCV)，注意大小写和拼写必须完全匹配 ——find_package(opencv4)才可能命中 - 用
message(STATUS "XXX_DIR = ${XXX_DIR}")在CMakeLists.txt里打印，确认变量真被读进去了，而不是拼写成XX_DIR或xxx_DIR
Module 模式 fallback 失败时怎么办？
当 Config 模式失败、CMake 自动切到 Module 模式后仍报错，说明它没找到 FindXXX.cmake。这时要主动干预：
- 先确认系统是否自带：Linux 上
find /usr -name "FindXXX.cmake" 2>/dev/null；Windows 上查 CMake 安装目录下的share/cmake-*/Modules/ - 自己写一个最简
FindXXX.cmake放进项目cmake/目录，然后加set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH}) - 别依赖
find_package(XXX REQUIRED)的自动逻辑 —— 如果你知道头文件和库在哪，直接用find_path(XXX_INCLUDE_DIR NAMES xxx.h PATHS /opt/xxx/include)和find_library(XXX_LIBRARY NAMES xxx PATHS /opt/xxx/lib)更可控
跨平台项目里最容易漏的一件事
Linux/macOS 上常靠 CMAKE_PREFIX_PATH 或环境变量（如 OpenCV_ROOT）生效，但 Windows 下注册表或 Visual Studio 工具链可能干扰查找顺序。真正保险的做法是：
- 在命令行调用 cmake 时显式传入：
cmake -DOpenCV_DIR=/path/to/opencv/lib/cmake/opencv4 -DCMAKE_PREFIX_PATH=/path/to/dep .. - 避免在
CMakeLists.txt里硬编码绝对路径（比如D:/Qt/...），改用相对路径或通过CMAKE_INSTALL_PREFIX推导 - 检查 CMake 版本：3.12+ 支持
PackageName_ROOT变量，优先级高于CMAKE_PREFIX_PATH，比XXX_DIR更可靠
复杂点在于：同一个库在不同安装方式（vcpkg、conda、源码编译、系统包管理器）下，提供的 Config 文件位置、命名、甚至是否存在，都完全不同。与其反复试错，不如先 ls 或 dir 看清真实文件结构，再决定走 Config 还是 Module，或者干脆绕过 find_package。
