根本原因是CMAKE_PREFIX_PATH未正确设置或库未按CMake标准目录结构安装；CMake默认仅搜索系统路径及CMAKE_PREFIX_PATH下子目录，且Config模式优先查找*Config.cmake文件，若路径中无对应配置文件则失败。
find_package 为什么找不到库？
根本原因通常是 CMAKE_PREFIX_PATH 没设对，或者库没按 CMake 期望的目录结构安装。CMake 查找逻辑默认只扫系统路径（如 /usr、/usr/local）和 CMAKE_PREFIX_PATH 下的子目录，不会自动递归扫描任意路径。
你手动编译安装的库（比如放在 /opt/mylib），如果没把 MyLibConfig.cmake 或 mylib-config.cmake 放在 /opt/mylib/lib/cmake/mylib/ 这类标准位置，find_package(MyLib) 就会失败——不是路径没指定，而是“指定的路径里没有它认得的配置文件”。
怎么让 find_package 扫指定路径？
最直接有效的方式是预设 CMAKE_PREFIX_PATH，而不是靠 HINTS 或 PATHS 参数临时硬塞。后者容易被策略覆盖，且不适用于 Config 模式查找。
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 命令行传入：
cmake -DCMAKE_PREFIX_PATH=/opt/mylib;/usr/local ..（多个路径用分号分隔，Windows 也是分号） - CMakeLists.txt 中提前设置：
set(CMAKE_PREFIX_PATH "/opt/mylib;$ENV{HOME}/local" CACHE PATH "Search prefix for find_package") - 注意：必须在
find_package()调用前设置，且不能用set(CMAKE_PREFIX_PATH ...)无CACHE的方式覆盖已有值（因为它是缓存变量）
find_package 的 Config 模式 vs Module 模式区别
这是很多人卡住的关键点：find_package(MyLib) 默认优先走 Config 模式（找 MyLibConfig.cmake），只有找不到才 fallback 到 Module 模式（找 FindMyLib.cmake）。而 HINTS 只影响 Module 模式，对 Config 模式无效。
- 想强制走 Module 模式：加
NO_MODULE是错的，正确是加MODULE参数：find_package(MyLib MODULE HINTS /opt/mylib/lib/cmake) - 想确认当前走的是哪种模式？打开调试：
cmake -DCMAKE_FIND_DEBUG_MODE=ON ..，终端会打印每一步尝试的路径和文件名 - 如果你只有头文件+静态库，没提供 Config 文件，那就老老实实写
FindMyLib.cmake放到项目cmake/Modules/下，并用set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/Modules" ${CMAKE_MODULE_PATH})
常见错误路径拼写和权限问题
CMAKE_PREFIX_PATH 值里多一个空格、少一个斜杠、路径不存在、或 MyLibConfig.cmake 里写的 set(mylib_INCLUDE_DIRS "...") 是相对路径但没用 ${CMAKE_CURRENT_LIST_DIR} 修正——这些都会导致 find_package 成功返回却后续编译报错。
- 检查 Config 文件是否真能被加载：在
MyLibConfig.cmake开头加message(STATUS "Loaded MyLibConfig from ${CMAKE_CURRENT_LIST_FILE}") - 避免绝对路径硬编码：Config 文件里用
${CMAKE_CURRENT_LIST_DIR}/../include，而不是/opt/mylib/include - Linux 下注意 SELinux 或文件权限：如果
MyLibConfig.cmake权限是600，CMake 读不了，会静默跳过
路径本身不难设，难的是让 CMake “理解”你给的路径里有什么、该怎么用——它要的从来不是路径，而是符合约定的元信息。
