博主介绍：程序喵大人

• 35 - 资深C/C++/Rust/Android/iOS客户端开发
• 10年大厂工作经验
• 嵌入式/人工智能/自动驾驶/音视频/游戏开发入门级选手
• 《C++20高级编程》《C++23高级编程》等多本书籍著译者
• 更多原创精品文章，首发gzh，见文末
• 👇👇记得订阅专栏，以防走丢👇👇
  😉C++基础系列专栏
  😃C语言基础系列专栏
  🤣C++大佬养成攻略专栏
  🤓C++训练营
  👉🏻个人网站

最近上线了一个网站（希加加职业发展平台），可以对简历进行评估、并且能够根据你的简历内容进行面试押题预测，分享给大家。各位有需要的同学也可以去网站上实践体验一下，希望能帮助到你~

你是不是也曾遇到过这些“玄学”问题：

• 明明 .cpp 和 .h 都写好了，编译通过，链接就炸
• 报错提示 undefined reference to SomeFunction()，但你分明写了实现
• 合并别人项目、引库、写 CMakeList、Makefile，总是神秘失败
• 一旦项目文件一多，就像走进“链接地狱”，调一天也找不到错在哪儿

别怕，这些困扰你多年的“未定义引用”其实并不神秘。

本文带你彻底梳理 C++ 从源文件到可执行文件的全过程。

一、C++ 编译链接流程全景图

C++ 编译过程可以拆解成四个阶段：

源代码（.cpp / .h）
   ↓（预处理）
.i 文件
   ↓（编译）
.s 汇编文件
   ↓（汇编）
.o 目标文件
   ↓（链接）
可执行文件

更形象一点：

g++ main.cpp utils.cpp -o app

这个命令背后其实做了：

1. 分别编译成 .o 文件
2. 链接所有 .o 文件 + 系统库，生成最终二进制

二、什么是 undefined reference？

错误提示大多像这样：

undefined reference to `MyClass::doSomething()`

这意味着：

你在某个地方声明/调用了 MyClass::doSomething()，但链接器找不到它的实现。

它不是语法错误，而是链接错误（Link-time error）。

也就是说，编译器承认你这么写是合法的，但链接器找不到“真实代码”。

三、最常见的 undefined reference 场景

我们来拆开看几个典型案例，并逐一解决。

场景 1：写了函数声明，但没有提供实现

// utils.h
void printMessage();

// main.cpp
#include "utils.h"
int main() {
    printMessage();
}

你以为没问题？但只写了声明，没有写实现！

g++ main.cpp -o app
# 错误：undefined reference to `printMessage()`

解决方法：

补上实现，或者确认链接时加了 .cpp 文件：

// utils.cpp
#include <iostream>
void printMessage() {
    std::cout << "Hello\n";
}

g++ main.cpp utils.cpp -o app

场景 2：忘记把源文件加进构建命令里

g++ main.cpp -o app
# 忘了 utils.cpp

这是最常见的手滑行为之一。

正确方式：

g++ main.cpp utils.cpp -o app

或者：

g++ -c main.cpp
g++ -c utils.cpp
g++ main.o utils.o -o app

场景 3：类方法只在头文件里声明了，在 .cpp 实现却没链接上

// MyClass.h
class MyClass {
public:
    void doSomething();
};

// main.cpp
#include "MyClass.h"
int main() {
    MyClass obj;
    obj.doSomething();  // undefined reference!
}

你确实写了实现…

// MyClass.cpp
#include "MyClass.h"
void MyClass::doSomething() {
    // ...
}

但你忘了把 MyClass.cpp 编译进去。

解决：

g++ main.cpp MyClass.cpp -o app

场景 4：模板类或函数写在了 cpp 里（经典坑）

// MyTemplate.h
template<typename T>
class MyBox {
public:
    void show();
};

// MyTemplate.cpp
#include "MyTemplate.h"
template<typename T>
void MyBox<T>::show() {
    // ...
}

这样写，链接一定报错。

为什么？

模板需要在 header 中定义实现，因为编译器要在“看到使用它的地方”就实例化代码。

正确方式：

要么把实现也写在 .h 里：

// MyTemplate.h
template<typename T>
class MyBox {
public:
    void show() {
        // 实现直接写这里
    }
};

要么用 .tpp 模板实现文件，在 .h 中包含：

#include "MyTemplate.tpp"

场景 5：链接时忘了加静态/动态库

// 使用某个库：libmath.a / libmylib.so
g++ main.cpp -o app

结果报错：

undefined reference to `sqrt'`

解决：

链接时手动指定库：

g++ main.cpp -lm       # 链接 math 库
g++ main.cpp -lprotobuf  # 如果你用了 protobuf

或者指定完整路径：

g++ main.cpp /usr/lib/libxyz.a -o app

场景 6：Makefile 漏文件 or 链接顺序错误

OBJS = main.o

但其实你用了 utils.cpp，编译也不会提示编译错误，只会链接时报：

undefined reference to `helper()`

Makefile 排查建议：

• OBJS 是否遗漏？
• 静态库/动态库顺序是否错误？（C++ 链接器顺序敏感！）

g++ main.o -lmystatic.a  # ✅
g++ -lmystatic.a main.o  # 可能出错

四、快速排查 undefined reference 的思路

✅ 遇到链接报错，可以按这个 checklist 走：

1. 是否漏写实现？（只写了声明）
2. 是否漏编译了对应 .cpp 文件？
3. 是否用了模板但实现没写在头文件？
4. 是否链接了需要的库？是否加了 -lxxx？
5. Makefile、CMakelist 编译目标是否漏了？
6. 是否多个定义（ODR 违例）？
7. 是否 extern/C 混用出错？

五、真实项目中推荐的构建方式

当项目逐渐变大，建议使用：

CMake 构建系统

add_library(myutils utils.cpp)
add_executable(main main.cpp)
target_link_libraries(main PRIVATE myutils)

• 自动处理依赖
• 支持跨平台构建
• 防止漏文件、链接错误

编译分步骤更安全

g++ -c main.cpp      # 生成 main.o
g++ -c utils.cpp     # 生成 utils.o
g++ main.o utils.o -o app

这样便于单独测试每个模块，也便于 IDE 集成和调试。

六、Linux 调试技巧 & 工具推荐

工具 / 技术	用途
nm	查看 .o / .a / .so 文件里导出的符号
readelf	查看 ELF 文件结构、符号表
objdump	汇编级反汇编工具
ldd	查看动态库依赖
strace	跟踪系统调用，确认库加载行为
g++ -v	打印详细编译过程

“未定义引用”并不可怕，它不是 C++ 的玄学，而是你对链接流程的不了解导致的。只要你掌握了：

• C++ 编译的四阶段流程
• 各类常见链接错误原因
• 模板/库/Makefile 的正确使用方式
• 快速排查技巧和工具链

你就能从每次都“人肉试错”，进阶到真正理解背后原理的工程师。

阅读推荐

• 《C++ Primer》第五章：编译与链接
• 《Effective C++》：了解编译器的优化行为
• Compiler Explorer：查看编译器生成的汇编代码

码字不易，欢迎大家点赞，关注，评论，谢谢！