最常见的原因是 target_link_libraries 调用顺序错误：必须在 add_executable 或 add_library 之后，且目标名严格一致；其次为库名错误，如应写 OpenCV::opencv_core 而非 opencv_core。
target_link_libraries 为什么链接不上库
最常见的原因是 target_link_libraries 调用顺序不对：它必须写在 add_executable 或 add_library 之后，且目标名要完全一致。CMake 不会回溯查找未定义的目标，写在前面直接报错 CMake Error: target "xxx" does not exist。
另一个高频问题是库名写错——比如你用 find_package(OpenCV REQUIRED) 找到了 OpenCV，但写成 target_link_libraries(myapp opencv_core)，而实际导出的 target 名是 OpenCV::opencv_core（注意大小写和双冒号）。现代 CMake 推荐优先使用 imported target 形式，而不是裸库名。
- 确认目标已声明：先
add_executable(myapp main.cpp)，再target_link_libraries(myapp ...) - 外部库优先用 imported target：
target_link_libraries(myapp PRIVATE OpenCV::opencv_core) - 系统库或自建库可用裸名，但需确保路径已通过
link_directories或target_include_directories补全（不推荐前者） - 避免混用 PUBLIC/PRIVATE/INTERFACE 不当：可执行文件一般用
PRIVATE，库接口暴露才用PUBLIC
STATIC vs SHARED 库链接行为差异
链接静态库（.a）和动态库（.so / .dll）时，target_link_libraries 本身不区分，但实际效果取决于库如何被导入或声明。如果你用 add_library(mylib STATIC src.cpp)，那它天然是静态的；若用 find_package 找到的库，则由其配置决定。
关键点在于：CMake 默认按“找到即链接”策略，不会自动 fallback。比如你机器上同时装了 OpenCV 的 shared 和 static 版本，find_package(OpenCV) 默认找 shared；想强制 static，得加 find_package(OpenCV REQUIRED CONFIG COMPONENTS opencv_core opencv_imgproc) 并确保 OpenCV_DIR 指向 static 构建目录，或设置 CMAKE_FIND_LIBRARY_SUFFIXES。
立即学习“C++免费学习笔记（深入）”；
- 静态链接可执行文件体积大，但部署免依赖；动态链接体积小，但运行时需
LD_LIBRARY_PATH或 rpath - 用
readelf -d myapp | grep NEEDED（Linux）或otool -L myapp（macOS）验证是否真连上了动态库 - 想让动态库路径嵌入二进制，加
set_target_properties(myapp PROPERTIES INSTALL_RPATH "$ORIGIN/../lib")
PRIVATE/PUBLIC/INTERFACE 三个关键字怎么选
这三个不是可有可无的修饰词，它们直接影响头文件搜索路径和依赖传递。比如你写 target_link_libraries(myapp PUBLIC fmt)，那所有链接 myapp 的下游目标也会自动获得 fmt 的头文件路径和链接项；而 PRIVATE 只作用于 myapp 自身。
典型误用：把第三方库（如 spdlog、Eigen）设为 PUBLIC 导致下游项目莫名多出 include 路径，甚至符号冲突。除非你在封装一个“接口库”，否则绝大多数情况应坚持“最小暴露”原则。
- 可执行文件：一律用
PRIVATE（它没有对外接口） - 你自己写的库（
add_library(mylib SHARED ...)）：内部依赖用PRIVATE，暴露给使用者的头文件依赖用INTERFACE，既需要链接又需头文件的用PUBLIC - 别对
find_package得到的 imported target 轻易用PUBLIC，尤其像 Boost、Qt 这类巨无霸
链接失败时怎么快速定位问题
最有效的办法不是反复改 target_link_libraries，而是先看 CMake 生成的 linker 命令行。运行 cmake --build build --verbose（或 make VERBOSE=1），搜 g++.*-o.*myapp 那一行，检查 -lxxx 是否出现、-L/path/to/lib 是否正确、顺序是否合理（Unix 下链接顺序敏感：被依赖的库要放在依赖它的库右边）。
如果看到 undefined reference to `xxx'，说明符号没解析到，常见原因有：函数声明了但没定义（.cpp 没加入源文件列表）、ABI 不匹配（比如用 Clang 编译的库被 GCC 链接）、模板未显式实例化、或者库根本没被传进 linker 命令（CMake 日志里压根没出现 -lxxx）。
- 确认库确实被找到：加
message(STATUS "OpenCV_LIBS = ${OpenCV_LIBS}")或message(STATUS "OpenCV_TARGETS = ${OpenCV_TARGETS}") - 检查 target 是否真正存在：
get_target_property(xxx_exists xxx TYPE)+if(NOT xxx_exists) - Windows 上注意
.lib（import lib）和.dll分离，链接的是.lib，运行时才要.dll
target_link_libraries 只是封装层。真正容易卡住的地方，往往不在语法，而在库的查找逻辑、target 作用域、以及跨平台 ABI 细节。 
