根本原因是CMAKE_PREFIX_PATH未正确设置或库未按CMake期望结构安装；CMake默认只搜索系统路径及CMAKE_INSTALL_PREFIX，要求FooConfig.cmake必须位于lib/cmake/Foo/等固定子路径下，且命名需与find_package(Foo)严格匹配大小写。
find_package 为什么找不到我的库？
根本原因通常是 CMAKE_PREFIX_PATH 没设对，或者库没按 CMake 期望的结构安装。CMake 默认只查系统路径（如 /usr、/usr/local）和 CMAKE_INSTALL_PREFIX，不会自动扫描你随便放的目录。
- 确认你的库是否包含
FooConfig.cmake或foo-config.cmake（大小写敏感，命名必须匹配find_package(Foo)中的名字） - 这个 config 文件必须在
lib/cmake/Foo/、share/cmake/Foo/或根目录下 —— CMake 只认这些固定子路径 - 如果只有
FindFoo.cmake（旧式模块），它不走路径查找逻辑，而是靠CMAKE_MODULE_PATH
CMAKE_PREFIX_PATH 是最常用且可靠的指定方式
它告诉 CMake “去这个前缀路径下找 lib/cmake/Foo/ 或类似结构”。多个路径用分号分隔（Windows）或冒号（Linux/macOS），但推荐统一用分号避免跨平台问题。
- 命令行指定：
cmake -DCMAKE_PREFIX_PATH="/path/to/my/install;/another/path" .. - CMakeLists.txt 中设置（需在
find_package前）：set(CMAKE_PREFIX_PATH "/path/to/my/install" CACHE PATH "") - 注意：不能用
set(CMAKE_PREFIX_PATH ...)不带CACHE，因为find_package在 configure 阶段读的是缓存值
别乱用 HINTS 或 PATHS 参数
find_package(Foo PATHS /opt/foo NO_CMAKE_ENVIRONMENT_PATH) 看似直接，但容易失效：
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
-
HINTS和PATHS只影响搜索顺序，不绕过 CMake 的路径规则；它仍会拼lib/cmake/Foo/这类子路径，如果你的库没放对位置，照样找不到 -
NO_CMAKE_ENVIRONMENT_PATH会禁用环境变量（如FOO_DIR），反而缩小搜索范围 - 仅当你要临时覆盖某个特定 config 路径时才用，日常开发优先用
CMAKE_PREFIX_PATH
验证路径是否生效？看 CMake 输出
加 -D CMAKE_FIND_DEBUG_MODE=ON 运行 cmake，它会打印每一步搜索路径和失败原因。重点关注：
- “Searching for FooConfig.cmake” 后列出的所有路径
- 是否出现了你期望的路径（比如
/my/lib/cmake/Foo/FooConfig.cmake） - 如果出现 “Found FooConfig.cmake in …” 但后续报错，说明是 config 文件本身有问题（比如硬编码了错误路径）
真正卡住的往往不是怎么指定目录，而是库的 install layout 和 config 文件内容没对齐 —— 这点比参数写法更值得花时间检查。
