根本原因是find_package不扫描全文件系统，只在预设路径查找特定命名的.cmake配置文件；即使库已安装，若路径未纳入搜索范围或缺失Config.cmake文件，就会静默失败。
find_package 为什么找不到你刚装的库
根本原因不是“库没装好”，而是 find_package 并不扫描整个文件系统，它只在预设路径里找特定命名的 .cmake 配置文件。哪怕你用 sudo apt install libopencv-dev 装了 OpenCV，如果系统路径没被 CMake 纳入搜索范围，或者包没提供标准的 OpenCVConfig.cmake，find_package(OpenCV) 就会静默失败。
常见现象包括：OpenCV_FOUND 为 FALSE、target_link_libraries 报错 “unknown target”，或 CMake 配置阶段直接中断（加了 REQUIRED 但没找到）。
- Ubuntu/Debian 系统下，apt 安装的库配置文件通常在
/usr/lib/x86_64-linux-gnu/cmake/opencv4/或/usr/share/cmake-3.*/Modules/，但 CMake 默认只查/usr和/usr/local的顶层子目录，不自动递归进lib/x86_64-linux-gnu - macOS Homebrew 安装的库（如
brew install eigen）配置文件多在/opt/homebrew/lib/cmake/eigen3/，而 CMake 默认不查/opt/homebrew - 手动编译安装到
/home/user/mylib的库，若没运行make install生成MyLibConfig.cmake，find_package(MyLib)必然失败
让 find_package 找到本地库的三种可靠方式
优先级从高到低：用 _DIR 环境变量 > 用 CMAKE_PREFIX_PATH > 用 PATHS 参数。它们都绕过默认路径限制，直指你的安装位置。
- 设置环境变量（推荐，一次设置，全局生效）：
export OpenCV_DIR=/usr/lib/x86_64-linux-gnu/cmake/opencv4
或 macOS：export Eigen3_DIR=/opt/homebrew/lib/cmake/eigen3
之后运行cmake ..即可，find_package会优先读取该变量指向的目录下的*Config.cmake - 传入
CMAKE_PREFIX_PATH（适合 CI 或临时构建）：cmake -DCMAKE_PREFIX_PATH=/opt/homebrew/lib/cmake ..
这个路径会被插入到所有查找逻辑的最前面，比系统路径更优先 - 在
CMakeLists.txt中硬编码PATHS（仅调试用，不推荐提交）：find_package(Boost REQUIRED PATHS /home/user/boost_1_85_0/lib/cmake/Boost)
注意：必须指向包含BoostConfig.cmake的**父目录**，不是.cmake文件本身
查不到 Config.cmake？试试 MODULE 模式或手动 fallback
有些老库（如旧版 Boost、Poco）只提供 Find*.cmake 模块，不带 Config.cmake。这时 find_package 会自动退回到 Module 模式——但它只查 CMAKE_MODULE_PATH 和 CMake 自带模块路径，不会主动扫描你的自定义安装目录。
- 把第三方
FindXXX.cmake放到项目cmake/目录下，然后在CMakeLists.txt开头加：list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake") - 如果连
Find*.cmake都没有（比如你手写的静态库），就别硬用find_package，改用底层命令：find_path(MYLIB_INCLUDE_DIR NAMES mylib.h PATHS /home/user/mylib/include)find_library(MYLIB_LIBRARY NAMES mylib PATHS /home/user/mylib/lib)
再手动target_include_directories和target_link_libraries - 检查是否真有
Config.cmake：find /usr -name "*opencv*Config.cmake" 2>/dev/null
没结果？说明 apt 包没自带，得自己编译安装或换用pkg_check_modules
容易被忽略的兼容性细节
find_package 的行为高度依赖 CMake 版本和库的打包质量。一个看似简单的调用背后，可能因路径大小写、版本号格式、组件名拼写而失败。
-
find_package(OpenCV 4.8 REQUIRED)要求OpenCVConfigVersion.cmake中声明的版本能兼容 4.8；如果实际是 4.9.0，且没声明兼容性，就会报错 - 包名大小写敏感：
find_package(eigen3)失败，但find_package(Eigen3)成功——因为配置文件名是Eigen3Config.cmake -
COMPONENTS必须精确匹配库提供的组件名：find_package(Boost REQUIRED COMPONENTS system thread)中thread在某些发行版里叫threads，拼错就Boost_FOUND为FALSE - Windows 下路径分隔符是反斜杠，但
CMAKE_PREFIX_PATH必须用正斜杠或双反斜杠，单反斜杠会被 CMake 当转义字符吃掉
真正卡住的时候，别猜路径，先运行 cmake -DOpenCV_DIR=/xxx -DCMAKE_VERBOSE_MAKEFILE=ON ..，看 CMake 输出里它到底去了哪些目录、加载了哪个 .cmake 文件——日志比文档更诚实。
