如何解决XLNT库编译链接时的undefined reference错误？

问题场景 #

在VS Code中使用GNU编译器（MinGW）构建基于xlnt库的C++程序时，编译通过但链接阶段报错，提示xlnt类的构造函数和成员函数未定义。程序代码如下：

#include <xlnt/xlnt.hpp>

int main() {
    // Create a new workbook and load an existing file
    xlnt::workbook wb;            // 第6行触发错误
    try {
        wb.load("example.xlsx");
    } catch (const std::exception& e) {
        std::cerr << "Error loading file: " << e.what() << std::endl;
        return 1;
    }
    return 0;
}

链接阶段错误输出：

[build] [ 50%] Building CXX object CMakeFiles/ExcelAccess.dir/src/ExcelAccess.cpp.obj
[build] [100%] Linking CXX executable ExcelAccess.exe
[build] C:/msys64/ucrt64/bin/../lib/gcc/x86_64-w64-mingw32/13.2.0/../../../../x86_64-w64-mingw32/bin/ld.exe: CMakeFiles\ExcelAccess.dir/objects.a(ExcelAccess.cpp.obj): in function main': [build] C:/Users/Public/Documents/Excel/src/ExcelAccess.cpp:6:(.text+0x19): undefined reference to xlnt::workbook::workbook()'
[build] C:/msys64/ucrt64/bin/../lib/gcc/x86_64-w64-mingw32/13.2.0/../../../../x86_64-w64-mingw32/bin/ld.exe: C:/Users/Public/Documents/Excel/src/ExcelAccess.cpp:8:(.text+0x4d): undefined reference to `xlnt::workbook::load(std::__cxx11::basic_string<char, std::char_traits, std::allocator > const&)'

xlnt库已成功编译完成，编译输出显示：

[main] Building folder: xlnt
[build] Starting build
[proc] Executing command: chcp
[proc] Executing command: "C:\Program Files\CMake\bin\cmake.EXE" -- build c:/xlnt/xlnt/build --config Debug --target all -j 42 --
[build] [ 11%] Built target libstudxml
[build] [100%] Built target xlnt
[driver] Build completed: 00:00:00.909
[build] Build finished with exit code 0

解决步骤 #

1. 修正CMakeLists.txt的库链接配置 #

链接错误的核心是CMake没有正确找到并链接xlnt库，需在项目的CMakeLists.txt中添加以下配置：

cmake_minimum_required(VERSION 3.10)
project(ExcelAccess)

# 强制启用C++11标准（xlnt依赖该标准）
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 指定xlnt的头文件目录（替换为你的xlnt/include实际路径）
include_directories("C:/xlnt/xlnt/include")

# 指定xlnt的库文件目录（替换为你的xlnt/build/lib实际路径）
link_directories("C:/xlnt/xlnt/build/lib")

# 添加项目源文件
add_executable(ExcelAccess src/ExcelAccess.cpp)

# 链接xlnt库
# 若为Debug编译，需链接带d后缀的库（如xlntd），Release则用xlnt
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    target_link_libraries(ExcelAccess xlntd)
else()
    target_link_libraries(ExcelAccess xlnt)
endif()

2. 确保编译模式一致 #

• 确认xlnt编译时用的是Debug还是Release模式，项目构建时必须选择相同模式，不能混合（比如xlnt编译Debug，项目也得用Debug构建）。
• 检查编译器一致性：xlnt和项目必须用同一套编译器（都是MinGW GCC），不能混用MSVC和GCC。

3. 验证库文件存在性 #

前往xlnt的build/lib目录，确认生成了对应的库文件：

• 静态库：libxlnt.a（Release）或libxlntd.a（Debug）
• 动态库：libxlnt.dll/libxlnt.lib（Release）或libxlntd.dll/libxlntd.lib（Debug）
  如果是动态库，需要将对应的.dll文件复制到项目可执行文件所在目录，或者添加到系统环境变量路径中。

内容的提问来源于stack exchange，提问作者Carlos Gonzalez