find_package(xxx) 链接失败的主因是xxx_dir路径下缺失匹配的xxxconfig.cmake文件，或虽存在但target名称错误、接口未传播、windows下debug/release库不全；需验证xxx_found、检查导入target名、用private链接、确保多配置支持。
find_package(XXX) 指定了 XXX_DIR 却链接失败，先确认它真找到了配置文件
很多人以为只要设置了 XXX_DIR，CMake 就一定走 Config 模式并成功加载——其实不然。CMake 会先检查 XXX_DIR 下是否存在 XXXConfig.cmake 或 xxx-config.cmake，如果文件名不匹配（比如大小写错、后缀漏了、名字拼错），它就直接忽略该路径，退回到 Module 模式重试，最终报“not found”。
常见现象：cmake .. -DXXX_DIR=/path/to/xxx 执行时没报错，但后续 target_link_libraries(myapp XXX::xxx) 提示目标未定义。
验证方法：在 CMakeLists.txt 中加一句 message(STATUS "XXX_DIR = ${XXX_DIR}")，再加 message(STATUS "XXX_FOUND = ${XXX_FOUND}")，运行 cmake 看输出是否为 TRUE。
XXX_DIR 路径下有 XXXConfig.cmake，但 target_link_libraries 还是报错
Config 模式成功加载后，库通常以 IMPORTED target 形式暴露，比如 OpenCV::opencv_core，而不是裸库名 opencv_core。直接写 target_link_libraries(myapp opencv_core) 必然失败。
正确做法取决于包本身提供的 target 名称，不是凭经验猜：
- 查看
XXXConfig.cmake文件里是否调用了add_library(... IMPORTED)，注意其NAME参数 - 或运行
cmake --debug-find -L（CMake 3.20+）观察 find_package 的详细日志，搜索 “Imported target” 关键字 - 更稳妥的是查文档或安装目录下的
share/xxx/或lib/cmake/xxx/里的Targets.cmake或xxxTargets.cmake
例如 OpenCV 安装后，常用的是 OpenCV::opencv_imgproc；而某些自建库可能只导出一个 MyLib::mylib。
链接失败是因为头文件路径或库路径没被正确传递
即使 find_package 成功且 target 存在，target_link_libraries 仍可能静默失败——因为 CMake 默认不自动传播 include 目录和 link interface。特别是当你的 target 是 STATIC 或 OBJECT 类型时，INTERFACE 属性不会自动继承。
典型症状：编译时报 “fatal error: xxx.h: No such file or directory”，但 find_package 明明成功了。
必须显式启用接口传播：
- 确保你用的是
target_link_libraries(myapp PRIVATE XXX::xxx)（PRIVATE 会把 INTERFACE_INCLUDE_DIRECTORIES 和 INTERFACE_LINK_LIBRARIES 一并拉进来） - 避免混用旧式变量方式，比如
include_directories(${XXX_INCLUDE_DIRS})+target_link_libraries(myapp ${XXX_LIBRARIES})，这容易遗漏依赖链 - 若用的是自定义构建的库，检查其
XXXConfig.cmake是否正确设置了set_target_properties(... PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "...")
Windows 下指定 XXX_DIR 后链接失败，大概率是 Debug/Release 混用
Windows 上很多库（如 Qt、OpenCV）默认生成两套库文件：xxx.lib（Release）和 xxxd.lib（Debug），对应不同的导入库名。CMake 的 Config 模式会根据当前构建类型（CMAKE_BUILD_TYPE）自动选，但如果你手动设置了 XXX_DIR，而该路径下只有一套（比如只有 Release 版），就会导致 Debug 构建时链接失败，错误信息常为 “cannot open input file xxxd.lib”。
解决办法：
- 确认
XXX_DIR指向的目录包含完整结构，例如lib/cmake/xxx/xxxConfig.cmake和lib/xxx.lib+lib/xxxd.lib - 或者显式告诉 CMake 使用哪套：在
find_package后加set(XXX_LIBRARY_DEBUG ${XXX_LIBRARY_RELEASE})（仅临时绕过，不推荐长期用） - 更健壮的做法是让库的
xxxConfig.cmake正确声明find_library的DEBUG/RELEASE模式，参考 CMake 官方find_library文档的CONFIG参数用法
真正麻烦的是那些没按规范打包的第三方二进制包——它们的 Config 文件压根没处理多配置，这时只能自己补写 FindXXX.cmake 或改用 pkg_check_modules。
