根本原因是find_package默认只查系统路径和CMAKE_PREFIX_PATH，不直接识别随意指定的目录路径；它会按固定规则拼接子路径（如lib/cmake/xxx）查找Config或Find文件，偏差即失败。
find_package 为什么找不到你放好的库？
根本原因不是路径写错，而是 find_package 默认只查系统路径和 CMAKE_PREFIX_PATH，它压根不认你随手传进来的「目录路径」参数。你写成 find_package(XXX PATHS /path/to/xxx) 或 find_package(XXX HINTS /path/to/xxx)，大概率还是失败——因为 CMake 不会直接去那个目录下找 XXXConfig.cmake 或 FindXXX.cmake，而是按规则拼接子路径（比如 /path/to/xxx/lib/cmake/xxx/），稍有偏差就跳过。
PATHS 和 HINTS 的区别到底在哪？
PATHS 是硬性指定搜索起点，但 CMake 仍会按固定后缀追加子路径（lib/cmake/xxx、share/xxx 等）；HINTS 优先级更高，且更尊重你给的原始路径结构，适合你已知 Config 文件就在某目录下。
- 用
HINTS：如果/opt/mylib/MyLibConfig.cmake存在，就写find_package(MyLib HINTS /opt/mylib) - 用
PATHS：如果库安装结构标准（比如/opt/mylib/lib/cmake/mylib/MyLibConfig.cmake），才用find_package(MyLib PATHS /opt/mylib) - 两者可叠加：
find_package(MyLib HINTS /home/user/local HINTS /opt/mylib)，顺序即优先级
比 PATHS/HINTS 更稳的三种做法
依赖路径不稳定时，靠参数临时指定容易漏或错。真正可靠的是提前把路径注入 CMake 的查找逻辑：
- 设置
CMAKE_PREFIX_PATH：在命令行传参，cmake -DCMAKE_PREFIX_PATH=/opt/mylib ..，之后所有find_package都自动查这个路径下的lib/cmake/等子目录 - 预设
CMAKE_MODULE_PATH：若用的是FindXXX.cmake（非 Config 模式），加set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/path/to/FindXXX.cmake") - 手动 include Config 文件：当其他方式都失效，直接
include(/path/to/MyLibConfig.cmake)，然后自己处理MyLib_FOUND和导入目标
常见错误现象和对应检查点
报错 Could not find a package configuration file 时，别急着改 PATHS，先确认这几件事：
- Config 文件名是否严格匹配：必须是
MyLibConfig.cmake或mylib-config.cmake（大小写敏感，且 CMake 会尝试多种变体） - 路径里有没有空格或中文：CMake 对含空格路径支持差，
/home/user/my lib/很可能被截断 - 是否混用构建类型：Release 构建去找 Debug 版 Config？检查
MyLib_DIR变量是否被上一次缓存污染 - 交叉编译场景下，
CMAKE_FIND_ROOT_PATH是否覆盖了你的自定义路径？它默认会过滤掉非 root_path 下的候选
最常被忽略的是：你改了 HINTS 路径，但没删 CMakeCache.txt，CMake 仍用旧缓存跳过新路径。每次换路径，先清理构建目录或至少删掉缓存文件。
