Qt 整合 C++ 函式庫：靜態庫與動態庫鏈接完整指南

兩種鏈接方式

靜態庫鏈接步驟

1. .pro 檔配置：

   INCLUDEPATH += $$PWD/../mylib/include
   LIBS += -L$$PWD/../mylib/lib -lmylib

2. C++ 程式碼直接 #include "mylib.h" 呼叫函式。
3. 執行 qmake → Build，符號解析於連結階段完成。

動態庫鏈接步驟

1. 庫專案導出標記 (CMake/qmake 專案)：

   // mylib_global.h
   #ifdef MYLIB_LIBRARY
   #  define MYLIB_EXPORT Q_DECL_EXPORT
   #else
   #  define MYLIB_EXPORT Q_DECL_IMPORT
   #endif
   
   class MYLIB_EXPORT MyClass { ... };

2. Qt 專案 .pro 配置：

   INCLUDEPATH += $$PWD/../mylib/include
   LIBS += -L$$PWD/../mylib/lib -lmylib

3. 執行階段尋找 DLL：
   • Windows：將 .dll 放在執行檔同目錄、系統目錄、或 PATH 環境變數路徑。
   • Linux/macOS：設定 rpath 或 LD_LIBRARY_PATH。
   • Qt 專案可用 QCoreApplication::addLibraryPath() 或部署腳本 windeployqt/linuxdeployqt 自動收集。

跨平台建置提示

# .pro 中區分平台
win32 {
    LIBS += -L$$PWD/lib/win32 -lmylib
}
linux {
    LIBS += -L$$PWD/lib/linux -lmylib
}
macos {
    LIBS += -L$$PWD/lib/macos -lmylib
}

常見問題排查

• LNK2019 / undefined reference：LIBS 路徑錯誤、庫未建置、導出宏未定義、呼叫慣例不符 (__stdcall vs __cdecl)。
• 執行時找不到 DLL：未部署 DLL、架構不匹配 (x86 vs x64)、缺少依賴庫 (用 Dependency Walker / ldd 排查)。
• 符號衝突：多個庫導出相同符號，改用命名空間或 version script 隱藏內部符號。

總結

Qt 整合 C++ 庫核心在 .pro 正確設定 INCLUDEPATH、LIBS，動態庫額外需處理 導出宏 與 執行階段 DLL 尋找路徑。善用 windeployqt/macdeployqt/linuxdeployqt 自動化部署，避免手動遺漏。