undefined reference 链接错误速查
更新时间：2026-10-24。FAQ 速查页，面向在 Linux/macOS 上用 gcc/g++ 与 makefile 构建 C/C++ 工程的同学。undefined reference 是链接阶段的招牌报错：编译全过了，最后一步链接器（ld）把所有
.o和库拼起来时，发现有人引用了某个符号、翻遍所有输入都找不到它的定义，只能停机。报错里引号中的符号名就是全部线索——它是定义所在的源文件根本没参与链接、库在命令行上顺序放错被 ld 跳过、C++ 名字修饰没加extern "C"、静态库互相依赖缺--start-group、库压根没装、还是符号被内联或宏吞掉，六根轴顺一遍基本必中。如果是 make 在更前面就报 No rule to make target，请转 make: No rule to make target 报错速查。
本文要回答的问题
undefined reference to 'foo'与 collect2 那行ld returned 1 exit status是什么关系？- 库明明在
-l里写了，为什么 ld 还说找不到符号？ - C++ 调 C 库为什么总是 undefined reference 的重灾区？
nm怎么判断一个库里到底有没有我要的符号？- 静态库互相依赖时
--start-group是干什么用的？
一、报错原文与典型现象
报错固定长这样（工程路径以 /proj/demo 占位）：
$ make
cc -o /proj/demo/build/app build/main.o build/net.o -L/proj/demo/lib -lutil
/usr/bin/ld: build/main.o: in function 'main':
/proj/demo/src/main.c:12: undefined reference to 'util_init'
collect2: error: ld returned 1 exit status
make: *** [Makefile:15: build/app] Error 1C++ 工程里则是带修饰名的变体：
/usr/bin/ld: build/demo.o: in function 'main':
/proj/demo/src/demo.cpp:8: undefined reference to 'cfg_load(char const*)'读懂报错抓住三件东西：符号名（缺谁）、引用位置（谁在用，文件+行号）、参与链接的输入（命令行上那串 .o 与 -l）。collect2: error: ld returned 1 exit status 只是 gcc 包装器转述 ld 的失败，不是新错误，真正的信息全在它上面那几行。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| 定义的源文件编译了但没进链接行 | 该 .o 没出现在链接命令里 | 看链接命令是否含对应 .o | 把源文件加入构建并参与链接 |
| 库里明明有该符号，ld 仍报缺 | -l 写在 .o 之前被 ld 跳过 | 看命令行顺序，nm 确认库里有符号 | 调整顺序：.o 在前，-l 在后 |
| 符号名是 C++ 修饰名，库是 C 写的 | 缺 extern "C"，名字修饰不匹配 | nm libxxx.a 看符号是否带修饰 | 头文件包 extern "C" { ... } 块 |
| 两个静态库互相引用 | 单次扫描解不开循环依赖 | 调整顺序后仍互报 undefined | -Wl,--start-group ... -Wl,--end-group |
| 报缺的是系统/第三方库符号 | 库没装或 -L 路径不对 | ldconfig -p | grep 库名 或 ls 库路径 | 装开发包（-dev/-devel），修正 -L |
| 头文件里声明了但没写定义 | 只有声明没有实现 | grep -rn "符号定义" src/ 无函数体 | 补上定义，或删掉多余声明 |
| 模板/inline 符号被吞 | 模板实例化或 inline 未生成实体 | 看定义是否在头文件里 | 模板定义放头文件，inline 按规范处理 |
| 库里符号有但被 strip/版本脚本藏了 | 符号可见性被限制 | nm -D --defined-only lib.so 查动态符号 | 调整可见性（默认导出）或换库 |
三、排查决策图
下面这张图是按「符号定义到底在哪」分岔的标准路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓住一个分水岭：先回答「这个符号的定义归谁管」。归项目（左支）多半是源文件没进链接行或定义根本没写；归外部库（右支）就是 ld 的扫描顺序、名字修饰、库是否装好这三件事。两分支的修法完全不重叠，先分清楚再动手。
四、逐条排查展开
第一步：确认定义在哪个库或源文件，用 nm 看实物。 nm 是链接排查的万用表：
nm /proj/demo/build/util.o | grep util_init
# 0000000000000000 T util_init （T = 有定义，U = 只有引用）
nm /proj/demo/lib/libutil.a | grep util_init
nm -D --defined-only /usr/lib/libfoo.so | grep foo_ # 动态库看导出符号T 说明定义在，U 说明这个文件只是引用方。如果定义所在 .o 根本没出现在链接命令里（makefile 里漏加了这个源文件），ld 自然找不到——把源文件加进构建并确保它参与链接即可。
库顺序是静态链接的第一大坑。 ld 对静态库是单次从左向右扫描：处理到 -lutil 时，只把「当前已知的未定义符号」能用上的成员拉进来；如果 -lutil 写在 main.o 之前，扫描到库时还没有任何未定义符号，库被整个跳过，后面 main.o 再引用就来不及了。修法一句话：.o 在前，-l 在后，被依赖的库放更后面。
C++ 调 C 库必查 extern "C"。 C++ 会做名字修饰（name mangling），cfg_load(const char*) 在目标文件里的符号名是一串带类型信息的修饰名；而 C 库里的符号是裸名 cfg_load。声明时不包 extern "C"，链接就是修饰名找裸名，永远找不到。报错里出现带参数列表的符号名（如 cfg_load(char const*)）基本就是这一条，修法是在 C 头文件外包：
extern "C" {
#include "cfg.h"
}更规范的做法是让 C 库头文件自带 #ifdef __cplusplus / extern "C" { 守卫。
静态库互相依赖用 --start-group。 A 库的符号依赖 B 库、B 又反过来依赖 A 时，任何线性顺序都解不开单次扫描，把这一团库包进组里让 ld 反复扫描直到收敛：
cc -o app main.o -Wl,--start-group -la -lb -Wl,--end-group库没装与符号被吞。 报缺的符号属于系统或第三方库时，先 ldconfig -p | grep 库名（Linux）或 ls /usr/local/lib（macOS）确认库在不在，不在就装开发包（Debian/Ubuntu 是 -dev、Fedora 是 -devel），再检查 -L 指向的目录对不对。另一类隐形坑是符号被吞：模板定义放在 .cpp 里别处实例化不到、inline 函数没有实体、宏把函数名替换掉了——这类用 nm 一查定义确实不在任何 .o 里，回去补定义或调整声明位置。
改完直接重链复验。 链接错误的闭环就是重新 make：命令行上能看到调整后的 -l 顺序与新加入的 .o，链接通过即修复确认；不过的话报错里的符号名会变，顺着新名字再走一遍本页流程。
五、规范做法与预防
- 链接命令模板化：makefile 里固定
$(CC) -o $@ $^ $(LDFLAGS) $(LDLIBS)的顺序——目标文件在前、库在后，杜绝手写乱序。 - C 头文件自带 extern "C" 守卫：库作者把守卫写进头文件，使用方永远不用记。
- 循环依赖从源头拆：能拆开的相互依赖就别用
--start-group硬撑，分层（底层库不回头依赖上层）是正解。 - CI 覆盖干净环境：开发机装过的库 CI 上没有，最容易暴露「库没装」这一类。
- 符号可见性显式管理：共享库用默认导出或版本脚本白名单，别让 strip/隐藏设置吞掉对外接口。
这一篇在知识体系里的位置
本篇是 Makefile 排错速查簇的链接篇，定位「编译全过、链接失败」：符号缺定义看本篇；更前面 make 展开规则就失败的看 make: No rule to make target 报错速查；用 CMake 生成构建系统、配置阶段连编译器都找不到的看 CMake 找不到编译器速查。nm、ldconfig -p、make -n 三件排查套在所有链接类报错间完全通用。
一句话总结
undefined reference 先用 nm 确认符号定义归谁管：归项目，多半是定义所在源文件没参与链接或只声明没实现，补进链接行或补定义；归外部库，八成是 -l 顺序放在了 .o 之前被 ld 单次扫描跳过，调整为「目标文件在前、库在后」，C++ 调 C 库给头文件包 extern "C"，静态库循环依赖用 -Wl,--start-group/--end-group，库没装就装开发包并核对 -L 路径；改完重新 make 复验。链接命令模板化、C 头自带 extern "C" 守卫、依赖分层不循环，这条报错即可基本绝迹。