链接失败本质是链接器找不到符号定义，需先确认undefined reference to后的XXX是自定义还是第三方符号，再用nm、objdump等工具定位缺失环节。
链接失败不是编译器的问题，而是符号找不到或路径没对上——先看错误信息里 undefined reference to 后面跟的是什么，再决定从哪下手。
报错是 undefined reference to XXX，怎么定位来源？
这类错误本质是链接器在目标文件和库中搜不到符号定义。别急着改 CMakeLists.txt，先确认这个 XXX 是你自己写的，还是第三方库里的：
- 用
nm -C libxxx.a | grep XXX或nm -C xxx.so | grep XXX查看静态/动态库是否真导出了该符号（注意加-C解析 C++ 名字修饰） - 如果是自己写的函数，检查它是否被
static修饰了，或者声明了但没实现（.cpp 里漏写了定义） - 如果是 C++ 函数，确认调用处和定义处的命名空间、类作用域、const 限定符完全一致——差一个
const就算不同符号 - 在 Linux 上，用
objdump -t your_target.o | grep XXX看目标文件里是U（undefined）还是T/W（defined）
CMake 中 target_link_libraries 写对了吗？
现代 CMake 推荐用目标式链接，而不是靠 link_directories() + 库名裸写。常见错法：
- 把库名写成
target_link_libraries(myapp PRIVATE pthread)—— 正确应是Threads::Threads（通过find_package(Threads REQUIRED)导入） - 混淆
PUBLIC/PRIVATE/INTERFACE：比如头文件依赖用了PRIVATE，下游 target 就看不到该库的 include 路径 - 顺序写反：链接器从左到右解析，依赖方必须写在被依赖方左边，
target_link_libraries(app PRIVATE A B)表示 A 依赖 B，B 必须已定义或已 find_package - 忘了
find_package(OpenCV REQUIRED)就直接写OpenCV::opencv_core，CMake 会静默忽略，导致链接时找不到符号
构建环境不一致导致链接失败，怎么排查？
同一份 CMakeLists.txt，在你本地能过，CI 或同事机器上报错，大概率是环境链路断了：
- 检查
cmake --debug-output输出里实际找到的库路径，确认不是误用了系统旧版库（比如 Ubuntu 自带的 OpenCV 4.2，而你代码需要 4.10） - Windows 上 VS 终端默认是 x86 工具链，但项目设了
-A x64，结果cl.exe走的是Hostx86\x86\cl.exe，链接器却去找x64版 .lib —— 错配必挂 - Mac 上注意
MACOSX_RPATH和@rpath设置，动态库路径硬编码容易在打包后失效 - WSL 或 Docker 构建时，挂载目录若来自 Windows NTFS，
cmake_symlink_library会直接报operation not supported on socket，得关掉BUILD_SHARED_LIBS或换本地路径构建
第三方预编译库链接不上，关键检查点
不是所有 .so/.a 都能直接塞进 target_link_libraries，尤其跨平台预编译库：
- 用
file libxxx.so确认架构（ELF 64-bit LSB pie executable x86-64）和 ABI（GNU/Linux还是HarmonyOS）是否匹配当前构建目标 - 某些库（如 Vulkan SDK）要求显式指定
find_package(Vulkan REQUIRED)，不能只靠link_directories+-lvulkan - Android NDK 下，
libc++_shared.so必须和你的APP_STL设置一致，否则std::string符号会找不到 - 鸿蒙 NDK 使用 lld 链接器，不支持部分 GNU ld 扩展语法，遇到
ld.lld: error: undefined symbol时，优先查nm输出里符号是否存在，而非怀疑 CMake 写法
真正卡住的时候，往往不是语法写错，而是某个库根本没被加载进来——nm 和 file 多跑两遍，比反复改 CMakeLists.txt 有效得多。
