C++ 链接错误：未定义的虚表引用排查

一个 C++ 服务编译时链接器报 undefined reference to vtable，最终根因是 CMake 源文件目录名拼写错误，导致类的实现文件没参与编译。这类报错本身很有通用性：只要「定义了第一个非 inline 虚函数的那个源文件」没被链接，构造函数就会报虚表未定义。本文记录完整定位过程与这个报错的通用成因。

问题现象

编译报错（节选）：

/usr/bin/ld: build/Server/CMakeFiles/Server.dir/src/handler_manager.cpp.o:
    in function `app::MetricMsgHandler::MetricMsgHandler()':
handler_manager.cpp:(.text._ZN3app16MetricMsgHandlerC2Ev[...]+0x1f):
    undefined reference to `vtable for app::MetricMsgHandler'

/usr/bin/ld: build/Server/CMakeFiles/Server.dir/src/handler_manager.cpp.o:
    in function `app::ExceptionMsgHandler::ExceptionMsgHandler()':
handler_manager.cpp:(...):
    undefined reference to `vtable for app::ExceptionMsgHandler'

构造函数里引用了 MetricMsgHandler 的虚表，但链接器在整个工程里找不到这张虚表。

原因分析

编译器（GCC/Clang 的 Itanium ABI）按 key function 规则生成 vtable：虚表只发射在「第一个非 inline、非纯虚的虚函数」所在定义的翻译单元里。因此只要这个函数没有实现、或实现它的源文件根本没参与编译链接，虚表就无处生成，构造函数引用虚表时即报此错。

具体两种可能：

1. 类的实现源文件不在构建系统搜索的路径内（没被加进目标）；
2. 类有虚函数（包括虚析构函数）声明了但没实现。

排查与解决

按两条线检查：

1. 实现文件是否在构建范围内：检查 CMakeLists.txt / Makefile 是否包含了该类源文件所在路径
2. 类是否实现了全部虚函数：检查本类，以及是否实现了父类的所有虚函数

本次的根因在第一条：CMakeLists.txt 里用了 AUX_SOURCE_DIRECTORY 自动收集源文件，目录名拼写错误：

AUX_SOURCE_DIRECTORY(src/topicHandle SRC_LIST)   # 实际目录是 topicHandler，少了个 r

修正后恢复编译：

AUX_SOURCE_DIRECTORY(src/topicHandler SRC_LIST)

AUX_SOURCE_DIRECTORY 在目录名拼错时不报「目录不存在」，只是安静地收集到空列表——这正是这类问题隐蔽的原因。

要点

• undefined reference to vtable 的机制：vtable 发射在 key function（第一个非 inline 非纯虚的虚函数）所在的翻译单元，该文件缺席则虚表缺失
• 排查顺序：先查实现文件是否进了构建目标，再查虚函数是否全部实现
• 用 AUX_SOURCE_DIRECTORY 这类「安静失败」的命令收集源文件时，目录名拼写错误不会产生任何警告；改用显式列举源文件或 GLOB 后加存在性检查更稳妥