根本原因是CMAKE_PREFIX_PATH未生效或路径格式错误；find_package在CONFIG模式下仅递归查找CMAKE_PREFIX_PATH各路径下的lib/cmake/xxx/、share/cmake/xxx/等标准子目录中的xxxConfig.cmake，且多路径必须用分号分隔，不可用冒号或空格。
find_package 为什么找不到我放好的 Config.cmake 文件？
根本原因往往是 CMAKE_PREFIX_PATH 没生效，或者路径格式错了。它不是“随便填个路径就行”的变量——find_package 在 CONFIG 模式下（默认行为）只会在 CMAKE_PREFIX_PATH 列出的每个路径下，递归查找 lib/cmake/xxx/、share/cmake/xxx/、share/xxx/cmake/ 等子目录里的 xxxConfig.cmake 或 xxx-config.cmake。如果你把 Qt6Config.cmake 直接丢在 /opt/qt6 根目录下，find_package(Qt6) 一定失败。
正确做法是确保结构合规：
-
/opt/qt6/lib/cmake/Qt6/Qt6Config.cmake✅ -
/home/user/mylib/share/cmake/mylib/mylibConfig.cmake✅ -
/tmp/mylib/MyLibConfig.cmake❌（不在标准子路径中）
CMAKE_PREFIX_PATH 多路径怎么写才不报错？
必须用分号 ; 分隔，不能用冒号 :、空格或换行。这是 CMake 内部解析逻辑决定的，和 shell 环境变量的 : 分隔完全无关。
命令行设置示例（推荐，最可控）：
cmake -DCMAKE_PREFIX_PATH="/opt/mydeps;/home/user/local" ..
Windows 下也一样，正斜杠更安全：
cmake -DCMAKE_PREFIX_PATH="C:/dev/openssl;C:/dev/curl" ..
常见错误：
-
-DCMAKE_PREFIX_PATH="/a /b"→ 当成单个路径/a /b，空格不会被拆分 -
export CMAKE_PREFIX_PATH=/a:/b（Linux）→ shell 会传给 CMake，但 CMake 把它当一个字符串，不识别冒号分隔 -
set CMAKE_PREFIX_PATH=C:\a;C:\b（cmd）→ 反斜杠需转义或改用正斜杠，否则可能被误解析为转义序列
PATHS 参数和 CMAKE_PREFIX_PATH 有什么区别？
PATHS 是 find_package() 的局部参数，只影响这一次调用；CMAKE_PREFIX_PATH 是全局变量，影响所有后续的 find_package()、find_library()、find_program() 等查找行为。
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
比如你只想让 find_package(OpenCV) 去特定位置找，其他包照常走系统路径，就该这么写：
find_package(OpenCV REQUIRED PATHS /opt/opencv-4.8.1/share/opencv4/cmake)
而如果整个项目依赖都装在 /opt/thirdparty，且结构统一（如 /opt/thirdparty/lib/cmake/eigen3/、/opt/thirdparty/lib/cmake/protobuf/），那就直接设 CMAKE_PREFIX_PATH 更干净，避免每个 find_package 都重复写 PATHS。
注意：PATHS 的优先级高于 CMAKE_PREFIX_PATH，但它不改变全局行为。
为什么设置了 CMAKE_PREFIX_PATH 还是找不到，但 _DIR 却可以？
因为 <packagename>_DIR</packagename> 是最高优先级的查找入口——它跳过所有路径扫描逻辑，直接加载指定路径下的 *Config.cmake 文件。例如：
find_package(Boost REQUIRED) # 失败，因为 BoostConfig.cmake 不在 CMAKE_PREFIX_PATH 覆盖范围内 set(Boost_DIR "/home/user/boost_1_85_0/lib/cmake/boost_system") find_package(Boost REQUIRED) # 成功，CMake 直接读取该路径下的配置文件
这适合调试或临时覆盖，但不适合工程化管理：每个库都要单独设 _DIR，维护成本高，且无法复用同一前缀下的多个组件（比如 boost_system 和 boost_filesystem 共享同一安装根目录）。
真正要长期稳定使用，还是得把路径结构对齐 CMake 的约定，并靠 CMAKE_PREFIX_PATH 统一注入。
