g++链接报undefined reference to的排查方法(静态库顺序、--start-group与nm -C、c++filt定位符号)

编译到链接那一步突然停下来,屏幕上刷出一片undefined reference to `add'和collect2: error: ld returned 1 exit status。代码明明已经#include了头文件,编译阶段也过了,说明不是语法问题,是GNU ld在把目标文件和库拼成可执行文件时没找到符号定义。这类报错在开发机上遇到过不止一次,十次里有七次是链接命令里-l的顺序摆反了。

/usr/bin/ld: main.o: in function `main':
main.cpp:(.text+0xf): undefined reference to `add'
collect2: error: ld returned 1 exit status


1、先确认符号真的在库里

别急着调顺序,先排除库里压根没有这种低级情况。

nm -C libfoo.a | grep add看输出,T是已定义的文本符号,U是未定义,W是弱符号。C++为了支持重载会把函数名改写成_Z3addii这种mangled名字,直接grep add往往什么都搜不到,nm -C或者把符号丢给c++filt _Z3addii还原成add(int, int)才对得上。

nm -C libfoo.a | grep add
c++filt _Z3addii

头文件里的C函数声明没按C链接方式处理,链接器找的是mangled名字,库里却是未mangled的,也会报undefined reference。之前接手过一份混编的工程,就是这个坑,头文件按C链接方式包一层就好了。

extern "C" {
#include "c_lib.h"
}


2、静态库的顺序是单遍扫描

GNU ld从左往右处理参数,遇到.o就把里面的未定义符号记进待解析表,遇到-lxxx只在这个库里找当前表里的符号,找到就抽出对应的.o,找不到就整库跳过,而且不会回头重扫。所以引用方必须排在库前面,A依赖B就写g++ main.o -lA -lB,反过来写B就被跳过了。

g++ -o main main.o -L. -lA -lB
ar cr libb.a b.o

两个库互相依赖,手工办法是把库重复列几遍,g++ main.o -lA -lB -lA。更省事的是让链接器在组内反复扫到收敛:

g++ -o main main.o -Wl,--start-group -lA -lB -Wl,--end-group

实测把整组库包进--start-group再编一次就过了,基本能坐实是顺序问题;代价是组内的库会被反复搜,链接明显变慢,只在这一小段用。动态库不受这个限制,符号在运行时解析,但很多发行版默认开了--as-needed,链接器认为程序没直接用到就把库丢掉,到运行时才报找不到符号,这时要显式加-Wl,--no-as-needed。


3、看一眼真实的链接命令行

手写的g++命令顺序一目了然,构建系统生成的未必。make VERBOSE=1、cmake --build . --verbose或者给链接器加-Wl,--verbose,能把最终那条命令完整打出来,很多Makefile和CMakeLists.txt会悄悄重排库顺序。

make VERBOSE=1
g++ -Wl,--verbose -o main main.o -lA -lB 2>&1 | grep attempt

CMake里别把所有库堆进同一个target_link_libraries靠运气,用PUBLIC、PRIVATE、INTERFACE把传递性写清楚,生成的顺序才是对的:

target_link_libraries(app PRIVATE A B C)

见过最绕的一次是CMake里七八个库全塞在一条target_link_libraries里,换台机器编就挂,本地却一直好,日志翻半天才发现是链接器版本不同导致顺序敏感程度不一样。


4、长得像但不是一回事的几种

还有几类报错外表接近,处理方式完全不同。multiple definition of `xxx'是符号重复定义,不是顺序问题;类里声明了虚函数或static数据成员却没写定义、模板的实现放在.cpp里没在用到的地方实例化、只跑了g++ -c没进链接、-L指错目录或者-l拼错名字(libfoo.a对应的是-lfoo,不是-lfoo.a),这几类查nm都能很快分辨。


GCC 13.2、14.1、14.2、14.3,binutils 2.41、2.42、2.43,CMake 3.28.2、3.30.0,这些组合上ld的单遍扫描规则都没变过;2023年到2024年那几轮工具链更新动的是别的部分。2026年手头这几台机器上复现,报错文本和上面贴的一致,数据截至2026年11月。

把库顺序当成依赖关系写出来,比事后靠--start-group兜底省事;按上面的步骤从nm查起,一般两三分钟能定位到是哪一个符号没对上。