链接阶段最后一行蹦出一句undefined reference to 'sqrt'，十有八九的人第一反应是回头翻math.h到底包含没包含、函数名是不是写成了sqr。我最早也这么干过，对着头文件来回看了半天才发现——这句话压根不是编译器说的，是链接器ld说的。它跟头文件、跟语法、跟函数名拼写，一点关系都没有。真正的原因往往只有一句话：你调用了数学库里的平方根函数，但没有把数学库交给链接器。

这篇东西就是把这件小事彻底说透。我会从"为什么这条报错属于链接期而不是编译期"讲起，然后解释为什么同一份代码在有些机器上不报错、改一个常量就报错，再给出一套能直接抄的复现步骤、三条查看链接链路的命令，最后分构建体系（命令行、Makefile、CMake、qmake/QML、交叉编译）给出具体写法。适合刚接触 C/C++ 构建的同学，也适合已经写了几年代码、但每次遇到这个错都靠"随手补一句 -lm"糊过去的人——后一种人其实更多。

1. 先把这个错归对类：它是链接错误，不是编译错误

1.1 gcc 一条命令背后的四段路

很多人把gcc main.c -o main当成一个原子操作，其实它内部拆成四步：预处理（cpp）把宏展开、头文件塞进来；编译（cc1）把 C 源码翻译成汇编；汇编（as）把汇编翻成目标文件.o；链接（ld）把一堆.o和库拼成一个可执行文件。

关键点在于：前三步都是针对单个源文件独立进行的，第四步才把所有人拉到一起。undefined reference这个词组只可能出现在第四步。所以当你看到报错信息长成这样：

/usr/bin/ld: /tmp/cc8xK2p.o: in function `main': main.c:(.text+0x1f): undefined reference to `sqrt' collect2: error: ld returned 1 exit status

开头那个/usr/bin/ld已经告诉你答案了。如果是编译期的问题，报错会以main.c:5:10: error:这种格式出现，带上文件名、行号和列号，甚至还会贴一段源码加个波浪线。链接期没有行号，因为它面对的是一堆二进制目标文件，早就不知道你的sqrt写在第几行了。

理解这一点非常实际。你去看头文件包含、去检查分号、去确认sqrt拼写，全是在错误的战场上浪费时间。正确的第一反应是：谁提供了这个符号？我把它交给链接器了吗？

1.2 头文件管"形状"，库管"实体"

这里要拆开一个新手最容易混淆的概念。#include <math.h>做的事情，是把一行声明塞进你的翻译单元：

extern double sqrt(double __x);

这行东西的作用只有一个——让编译器知道：有一个叫sqrt的函数，接收一个double，返回一个double。有了这个"形状"信息，编译器就能正确地生成调用代码：把参数放进寄存器，然后留一条跳转指令，跳向符号sqrt。

但函数体在哪？在libm里。头文件从来不含实现，它只是一张名片。

打个比方：math.h是电话簿上的一行字"张三，138xxxxxxxx"，libm是真正接电话的那个人。你翻了电话簿，知道了号码格式是合法的，但电话打出去没人接——这就是undefined reference。包含头文件成功，只能证明"格式对"，完全不能证明"人在"。

所以这两件事是正交的：math.h缺失 → 编译期报implicit declaration of function 'sqrt'；libm没链接 → 链接期报undefined reference to 'sqrt'。同一句代码可以只中一个，也可以两个都中。分清楚报错来自哪一段，排查效率能差出十几倍。

1.3 链接器为什么不说"你要加 -lm"

有人会问：链接器既然知道符号名叫sqrt，难道不知道它属于libm吗，为什么不直接提示？

答案很朴素：链接器真的不知道。符号和库之间的对应关系不存在于链接器内部的知识库里。同一台机器上，libm.so里有sqrt，你自己写的libmine.so里也可以有一个sqrt，链接器凭什么替你决定用哪个？它只会老老实实地报告：在所有你给我的输入里，我找不到sqrt的定义。

这个设计其实是对的做法。如果链接器自作聪明去猜，那符号冲突、版本覆盖这类问题会变得完全不可控。代价就是——加库这件事必须由你显式做。

2. 为什么有时候不加 -lm 也能编过

2.1 常量折叠：改一行代码，报错就消失了

这是最让人抓狂的场景。先看第一段代码：

#include <math.h> #include <stdio.h> int main(void) { printf("%f\n", sqrt(2.0)); return 0; }

gcc t.c -o t，直接过，连-lm都不用加。你再改成这样：

#include <math.h> #include <stdio.h> int main(void) { double x = 2.0; printf("%f\n", sqrt(x)); return 0; }

gcc t.c -o t立刻报undefined reference to 'sqrt'。

为什么会这样？因为 GCC 有一个叫常量折叠的优化：当sqrt的参数是编译期就能确定的字面量时，编译器干脆在编译阶段把结果算出来，直接写进目标文件。第一段代码里sqrt(2.0)直接被替换成1.414214这个浮点常量，目标文件里对这个符号没有任何引用，链接器自然无事可做。

第二段里x是个运行期变量，编译器不知道它的值（哪怕它上一行刚赋过值，只要没开优化到极致，也不行），只能老老实实生成一条call sqrt指令。这条指令在目标文件中留下一个未解析的符号，链接器必须找到定义，找不到就报错。

我见过不少人因为"刚才还能编过，我就加了个变量怎么就崩了"，开始怀疑自己的逻辑写错了。其实逻辑一点没错，只是常量折叠消失了。

2.2 GCC 内建函数在这个过程里的角色

GCC 会把一批数学函数识别为"内建函数"（builtin），sqrt、sin、cos、pow、fabs都是。识别成内建之后，编译器在优化阶段可以做的事情就多了：常数折叠、指令替换、参数检查。

想确认编译器到底有没有真的生成对sqrt的调用，有几个办法：

• gcc -O2 -S t.c生成汇编，grep 'call.*sqrt'看有没有这条调用；
• gcc -c t.c && nm -u t.o，输出里如果有U sqrt，说明这个符号没有被解析，链接时就必须靠库来填；
• 加-fno-builtin或更精确的-fno-builtin-sqrt强制禁用内建，让编译器老老实实按普通函数调用处理。

这里有个实操上的小坑：-fno-builtin写在源码文件前面和后面，效果可能一样，但在某些老的构建脚本里，如果它出现在-O2之前，是会被后来的优化选项部分覆盖的。我一般把它直接跟在目标文件后面写，图个心安。

2.3 顺带说一句：能不能彻底不依赖 libm

能。加-fno-math-errno（-ffast-math会把它包含进去）之后，GCC 被允许把sqrt(x)编译成一条硬件平方根指令。在 x86-64 上就是sqrtsd，一条指令搞定，根本不需要调用函数，也就不需要链接libm。

但代价要看清楚：-fno-math-errno告诉编译器"你不需要按 C 标准的要求在出问题时设置errno"，-ffast-math更激进，还会放弃 NaN/Inf 的部分特殊值语义、改变浮点结合律。如果你在做严格的数值计算、或者依赖边界值行为的逻辑，开这个就是给自己埋雷。

我的原则是：性能不敏感的代码一律不开，性能敏感的代码开了之后必须补一套边界用例测试。为了省一句-lm去改浮点语义，这笔账怎么算都不划算。

3. 三条命令把链接链路钉死

3.1 最小复现，先建立确定的事实

新建三个文件，分别是a.c、b.c、c.c，内容就是上面那个sqrt(x)版本，只是变量名不同。然后逐个编译：

gcc a.c -o a # 报 undefined reference to `sqrt' gcc a.c -lm -o a # 还是可能报（见第 4 节） gcc a.c -o a -lm # 过

注意第三行和第二行的差别——-lm的位置。这是第 4 节要展开的内容。先在命令行上把这两种写法都试一遍，亲手确认一下顺序确实会影响结果，比看十篇文章都管用。

3.2-Wl,-y：让链接器自己说清楚

ld有一个非常好用但很少有人知道的选项-y symbol，作用是：打印所有引用了这个符号的地方，以及所有定义了它的地方。通过gcc转发给链接器要写成-Wl,-y,sqrt：

gcc a.c -o a -lm -Wl,-y,sqrt

输出里会出现类似这样的行：

a.o: reference to sqrt /lib/x86_64-linux-gnu/libm.so.6: definition of sqrt

第一行告诉你"谁在用"，第二行告诉你"谁提供的"。把它和报错信息放在一起看，"缺失"这件事立刻就从抽象变具体了。如果第二行压根不出现，那就是库没链接上，方向明确。

这个技巧我第一次用的时候有种"原来链接器早就知道，只是没主动说"的感觉。它比在构建脚本里瞎试快得多。

3.3nm、readelf、ldd三件套

想再往下挖一层，配合下面这几条：

nm -u a.o # 列出目标文件里所有未定义符号 nm -D /lib/x86_64-linux-gnu/libm.so.6 | grep ' sqrt' readelf -d a | grep NEEDED # 看最终可执行文件依赖了哪些 .so ldd a # 运行时依赖列表

第一条命令是排查的起点。如果nm -u a.o里出现了U sqrt，说明链接必须解决它；如果压根没出现，说明编译器内联掉了，那报错一定是别的原因。

第二条确认库本身确实提供这个符号。某些精简过的嵌入式根文件系统里，libm被裁掉了部分函数，这时候nm一下就能看出来。

readelf -d和ldd用在"已经编过了但行为不对"的场景，比如你加了-lm但程序跑起来还是异常，可以确认NEEDED里到底有没有libm.so.6。这里有个细节：如果你用-static链接，readelf -d什么都不会输出，因为根本没有动态段，别被这个吓到。

3.4 看一眼真实的链接命令

还有一个终极手段：让gcc把它实际执行的链接命令打出来。

gcc -v a.c -o a 2>&1 | tail -3

输出的最后几行会是一条完整的collect2调用，里面包含了所有-l选项和它们的顺序。构建系统里那些"我明明配置了"的问题，看这条真实命令往往一眼就破。CMake、qmake 这类工具生成的链接命令，和你在配置文件里写的意图之间，隔着一层翻译，出偏差是常事。

4. 加了 -lm 还报错，问题基本都在顺序上

4.1 链接器是从左往右扫的

传统 Unix 链接器的扫描模型是这样的：从左到右依次处理命令行上的每个输入，遇到未定义符号就记下来，遇到能提供符号的目标就填坑，扫完之后还有没填上的就报错。

这个规则对静态库尤其致命。静态库.a本质上是一堆.o打包，链接器只会从里面挑出"当前确实需要的"那些成员。如果你把库写在需要它的目标文件前面，链接器扫到库的时候，符号还没被引用，它认为这个库没用，直接跳过；等到后面扫到.o、发现缺符号时，库已经过去了，不会回头。

正确顺序只有一条：引用者在前，提供者在后。

gcc main.o -lm -o main # 建议的写法 gcc -lm main.o -o main # 静态链接场景下会出问题

这里要泼一盆冷水，也是很多网上教程说错的地方：在动态链接场景下，gcc -lm main.c往往是能编过的。因为共享库的符号解析是全局的，libm.so一旦被记入链接，链接器最终会把它放进NEEDED里，符号查找不受扫描顺序限制。所以"顺序问题"这个坑不会在你随手写的 hello world 里暴露出来。

真正会被它坑到的场景有三个，都很常见：

• 用-static做静态链接，链接的是libm.a，扫描顺序变成硬约束；
• 嵌入式工具链里只提供静态库的libm.a；
• 链接你自己写的静态库，且库之间还有依赖关系。

第三种情况最阴。比如libA.a里的函数调用了libB.a里的函数，命令行必须写成-lA -lB。写成-lB -lA就会报一个看起来毫无道理的undefined reference。这个规则和sqrt没直接关系，但同一个道理，遇到"库与库之间的符号找不到"时，第一件事就是检查顺序。

4.2--as-needed会把顺序问题放大

很多主流发行版的 GCC 默认带了-Wl,--as-needed。它的含义是：只有当某个库真的提供了被用到的符号时，才把它写进最终可执行文件的NEEDED列表。

这个开关的初衷是减小依赖、加快启动，副作用是让顺序错误更难被发现，也更难排查。顺序错了，链接器认为这个库"没用上"，于是不写进NEEDED；程序编过了，运行时报找不到符号，或者干脆行为异常。

想临时关掉看看效果，可以加-Wl,--no-as-needed再链一次。如果加上就正常了，基本能确认是顺序或者--as-needed判断的问题。

4.3 静态库之间的循环依赖

如果两个静态库互相调用，单纯调顺序已经救不了了，得上分组：

gcc main.o -Wl,--start-group -lA -lB -Wl,--end-group -o main

--start-group和--end-group之间的库会被链接器反复扫描，直到没有新的符号可以解析为止。代价是链接变慢，所以只在真的需要时用。我一般会在注释里写清楚为什么加了这组标记，不然接手的人过半年看到会一头雾水。

5. 不同构建体系下该怎么写

5.1 命令行与 Makefile

命令行最简单：把-lm追加到所有目标文件后面。

Makefile 里要注意区分变量。GNU make 的内置链接规则大致是这样的形式：

$(CC) $(LDFLAGS) $(TARGET_ARCH) $^ $(LOADLIBES) $(LDLIBS) -o $@

顺序上$^（所有依赖，也就是.o文件）在LDLIBS前面，所以库应该写进LDLIBS，而不是LDFLAGS。LDFLAGS出现在最前面，写在那里就正好踩了第 4 节的顺序坑。

CC = gcc CFLAGS = -O2 -Wall LDLIBS = -lm calc: main.o solver.o $(CC) $(CFLAGS) $^ $(LDLIBS) -o $@

如果你的项目里出现了sqrt、pow、log、atan2一起报错的情况，别一个一个加，它们全在libm里，一句-lm解决。这是判断"是不是缺 libm"的一个快速信号：报错的符号成组出现，且都是数学函数。

5.2 CMake：别在 Windows 上写死 m

CMake 里最直接的写法是：

target_link_libraries(myapp PRIVATE m)

但这句在 Windows 上会出问题——MSVC 工具链里没有独立的libm，数学函数在 C 运行时里，写m会找不到库。跨平台项目要做条件判断：

include(CheckLibraryExists) check_library_exists(m sqrt "" HAVE_LIB_M) if(HAVE_LIB_M) target_link_libraries(myapp PRIVATE m) endif()

或者用find_library：

find_library(MATH_LIBRARY m) if(MATH_LIBRARY) target_link_libraries(myapp PRIVATE ${MATH_LIBRARY}) endif()

这两种写法的差别值得说一句。check_library_exists是探测"这个库里有没有这个符号"，语义更准确；find_library只是找库文件存不存在，理论上可能出现文件存在但符号缺失的情况（裁剪过的嵌入式根文件系统）。我个人偏好check_library_exists，多花几秒配置时间，换来的是更确定的结论。

还有一个 CMake 层面的经验：链接关系尽量用PRIVATE/PUBLIC表达清楚。如果sqrt的调用发生在某个内部静态库的源文件里，那m应该PRIVATE链在那个静态库上，而不是链在最终可执行文件上。前者是"谁用谁负责"，后者容易随着重构漏掉。我在几个项目里都遇到过"重构完之后某个子模块编不过"，根因就是链接依赖挂错了层级。

5.3 qmake / QML 工程里的坑

Qt 项目里出现undefined reference to 'sqrt'，通常有两种来路：一是你在 C++ 侧自己加了一个.c文件或引用了第三方 C 库；二是某些 Qt 模块的底层实现间接用到了平方根，而工具链配置不完整。

qmake 里加库要用LIBS：

LIBS += -lm

不要用QMAKE_LFLAGS += -lm。这是我在真实项目里踩过的坑，值得展开说。

QMAKE_LFLAGS里的内容会被拼接到链接命令的靠前位置，而LIBS里的内容会被拼到目标文件和 Qt 库之后。qmake 生成的典型链接命令长这样（简化过）：

g++ <QMAKE_LFLAGS> -o app main.o widget.o -L... -lQt5Core -lQt5Gui ... <LIBS>

把-lm塞进QMAKE_LFLAGS，它就跑到main.o前面去了。在静态链接或者某些交叉工具链下，这个位置会导致符号找不到。而放进LIBS，它稳稳地待在最后，符合"引用者在前、提供者在后"的规则。

这个问题之所以阴，是因为它在你的开发机上可能完全不报错（动态链接、--no-as-needed），一到 CI 或者交叉编译环境就炸。我当时排查了两天才定位到是变量选错了，现在写 qmake 工程一律只用LIBS。

另外提一句 QML 相关的报错。如果你看到的是 QML 运行时的类型错误或者qmlscene加载失败，那和sqrt无关，别混为一谈。undefined reference to 'sqrt'一定发生在编译链接阶段，和 QML 引擎没有关系，QML 只是恰好在同一个工程的构建流程里。

5.4 交叉编译与嵌入式工具链

这一块的坑比本地编译多得多，因为工具链的构成千差万别。

第一种情况是工具链只提供静态库。很多厂商提供的 ARM 工具链里，libm.a是主力，甚至没有libm.so。这时候顺序要求就变成硬性的，-lm必须写在所有.o之后。

第二种情况是 sysroot 配错，链接器跑到宿主机的/usr/lib里去找libm。表现是链接能过，但程序在目标板上跑不起来（架构不匹配），或者报一堆奇怪的符号版本问题。排查时可以看链接命令里-L的路径，确认指向的是工具链的 sysroot 而不是宿主机目录。

第三种是-nostdlib/-nodefaultlibs场景。这两个选项会阻止编译器自动加入标准库和启动文件，常见于写裸机程序或者自己实现运行时的时候。这种情况下libm也不会被自动加，必须手动链接，而且顺序和启动文件的关系也要理清楚。

第四种是 newlib 之类的精简 C 库。它的libm同样是独立的一份，需要显式-lm。有些厂商在工具链的 spec 文件里做了预置，换个版本就失效了，所以别指望它。

Android NDK 项目里，libm和liblog都是需要显式声明的。CMake 写法如下：

target_link_libraries(native-lib PRIVATE m log)

m代表数学库，log是日志库。这两个是 NDK 开发里最常被漏掉的一对。

6. 一张对照表，几种典型场景怎么处理

6.1 现象、根因、处理对照

6.2 几个容易走偏的方向

去改头文件包含路径。math.h只要能被找到一次就够，改-I对这个错误毫无帮助。

以为要装什么开发包。libm从来不单独发布，它和 C 运行库是一起装的。系统上找不到libm通常意味着 C 库本身缺失，那是另一个量级的问题。

在 C++ 里给它套extern "C"。sqrt本来就是 C 符号，<cmath>已经处理好了名字修饰的事，再套一层没有任何作用，反而可能因为嵌套写法出错。

认为加-lm会影响性能。加库只是让链接器知道去哪里找符号，对生成的代码没有直接影响。真正影响性能的是-O级别和浮点选项。

把-lm当成万能补丁到处加。如果某个.c文件根本没用到数学函数，给它链接libm只是徒增依赖。我在一个项目里见过十几个模块全都挂-lm，最后谁也不知道到底是哪个模块真的需要它。

6.3 我自己的处理习惯

• 在项目最底层的构建脚本里做一次平台判断，把数学库抽象成一个目标或者变量，业务代码只管引用，不在各处散落-lm。
• 报错符号成组出现时，先按"缺库"而不是"缺代码"来假设，nm -u一条命令就能验证。
• 遇到"改了一行就报错"的情况，第一反应是常量折叠，而不是逻辑问题。
• 静态链接的项目单独跑一轮完整构建，因为顺序问题只在静态链接下才会暴露。

7. 写在经验之后

undefined reference to 'sqrt'这个问题本身只有一行解法，但它牵扯出来的东西比看上去多得多：编译期和链接期的分界、头文件与库的职责划分、常量折叠对内联的影响、链接器从左到右的扫描模型、--as-needed的副作用、各构建工具对命令行顺序的控制能力。

我在实际项目里判断一个人对构建系统的熟悉程度，有个土办法：问他"为什么gcc main.c -lm和gcc -lm main.c有时候都能过"。能说清楚动态链接和静态链接差异的人，大概率也踩过交叉编译的坑、也知道 CMake 的链接依赖该怎么分层。

最后再分享一个我用了好几年的小习惯：凡是在命令行上手试出来的链接参数，必须在构建脚本里原样复现一次，并且验证生成的链接命令。用gcc -v或cmake --build . --verbose把真实命令行打出来看一眼，比在配置文件里反复猜快得多。链接问题几乎从来不是"想不明白"，而是"没看到真正的命令行长什么样"。把那条命令看清楚，剩下的事情基本就只剩填空了。