undefined reference 的本质是链接器未找到符号定义，而非头文件问题；需确保 -L 指定库路径且在前、-l 指定库名（不含前缀后缀）且在后，顺序错误或缺失任一参数均导致链接失败。
Clang 链接第三方库失败，绝大多数情况不是库本身有问题，而是链接器压根没找到符号定义——undefined reference 是假象，ld: library not found 才是真问题。
为什么头文件能跳转但报 undefined reference？
这是最典型的误导性现象：IntelliSense 或 clangd 显示正常、#include 不红、Ctrl+Click 能跳转到声明，说明 -I（头文件路径）已生效；但链接时找不到函数体，本质是缺 -l（库名）和/或 -L（库路径）。
-
-I只负责让编译器看见.h里的声明 -
-L/path/to/lib告诉链接器“去这个目录里找库文件” -
-lfoo告诉链接器“去找libfoo.a或libfoo.so”，注意不含lib前缀和后缀 -
-L必须写在所有-l之前，顺序错就等于没写
macOS / Linux 下 OpenCV、Boost 等常见库怎么链？
别硬背路径和库名，用工具查真实参数：
- Linux/macOS 上运行：
pkg-config --libs opencv4（或opencv5），输出类似-lopencv_core -lopencv_imgproc -L/usr/lib/x86_64-linux-gnu - Homebrew 安装的库，典型路径是
/opt/homebrew/lib（Apple Silicon）或/usr/local/lib（Intel） - vcpkg 安装的库，路径通常是
vcpkg/installed/x64-osx/lib - 静态库（
.a）和动态库（.so/.dylib）都需-l+-L，不能只加头文件路径
VSCode tasks.json 里 -L 和 -l 怎么写才不被忽略？
tasks.json 的 args 是命令行参数的直接映射，空格、顺序、引号一个都不能错：
-
-L"/path/with spaces"：路径含空格必须用双引号包裹 -
-L/opt/homebrew/lib -lopencv_core -lopencv_imgproc：-L在前，多个-l可连续写 - 别写成
-L/opt/homebrew/lib -lopencv_core -L/usr/local/lib——第二个-L后面没跟-l，链接器会忽略它 - 如果用 Code Runner 插件，它不读
tasks.json，得改settings.json里的code-runner.executorMap.cpp字段，把完整命令塞进去
Clangd 补全正常但编译失败？检查 compile_commands.json
clangd 依赖 compile_commands.json 获取真实编译参数，包括第三方库路径。没有它，补全可能靠猜，而编译器认死理：
- CMake 项目：配置时加
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON，生成该文件 - ROS 2 项目：先装
python3-colcon-json，再执行colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON - 手动补救：在项目根目录建
.clangd文件，写：CompileFlags: Add: [-I/path/to/third_party/include, -L/path/to/third_party/lib]
- 系统级库（如
/usr/include）通常自动识别，但非标准路径必须显式声明
最容易被忽略的是：链接器不关心你 #include 了什么，只认 -l 和 -L 是否出现在最终命令行里——哪怕 clangd 补全完美，只要构建命令漏掉一个 -l，就必然 undefined reference。
