Qt 專案整合 MySQL 庫衝突問題排查與解決

前言

Qt 專案若同時連結系統安裝的 MySQL C API 庫與 Qt 內建的 SQL 驅動插件，極易發生符號衝突、執行緒安全、記憶體管理不一致等難以除錯的問題。本文記錄實際遇到的 QDir 讀取異常、system() 返回 32512 等詭異現象，以及透過自行編譯 Qt MySQL 驅動解決衝突的過程。

問題現象

• QDir 讀取檔案間歇性失敗 (有時可讀、有時不可讀)
• system() 執行外部命令間歇性失敗，返回值 32512 (對應 ECHILD 或 Shell 執行失敗)
• 錯誤無固定重現步驟，極難定位

排查過程

1. 逐一註解程式碼區塊，鎖定「插入資料庫操作」觸發問題
2. 確認專案使用 系統安裝的 MySQL C API (libmysql.dll/.so)，而非 Qt 內建驅動
3. 同事其他專案使用相同庫無問題，排除庫本身缺陷
4. 專家建議：Qt 內建 MySQL 驅動與外部 MySQL 庫版本/編譯選項不一致導致衝突

解決方案：自行編譯 Qt MySQL SQL 驅動插件

步驟

# 1. 取得 Qt 原始碼 (對應版本)
# 2. 進入 Qt SQL 驅動原始碼目錄
cd /src/plugins/sqldrivers/mysql

# 3. 使用目標 MySQL 開發套件編譯
qmake "INCLUDEPATH+=/usr/include/mysql" "LIBS+=-L/usr/lib/mysql -lmysqlclient" mysql.pro
make
# 或 Windows
qmake "INCLUDEPATH+=C:/MySQL/include" "LIBS+=C:/MySQL/lib/libmysql.lib" mysql.pro
nmake

部署

• 將產生的 qsqlmysql.dll (或 libqsqlmysql.so) 複製至專案輸出目錄或 Qt 插件目錄 (plugins/sqldrivers/)
• 確保執行階段載入的 libmysqlclient 版本與編譯時一致

核心原理

• Qt SQL 模組透過插件架構載入驅動，插件編譯時連結的 MySQL 庫版本必須與執行階段一致
• 系統安裝的 MySQL 可能為不同版本、不同編譯器 (MSVC/MinGW/GCC)、不同執行緒模型
• 混用導致符號解析錯誤、TLS (Thread Local Storage) 不一致、堆疊損毀等未定義行為

最佳實踐建議

• 統一工具鏈： Qt、MySQL Client Library、專案皆使用相同編譯器 (MSVC 2019 / MinGW / GCC)
• 使用 vcpkg/Conan 管理依賴： 確保版本一致性
• 靜態連結 Qt： 可避免插件載入衝突，但授權需符合 LGPL/商業授權
• Docker 容器化建置： 鎖定完整建置環境，確保可重現

總結

Qt 整合第三方 C 庫時，編譯器、標準庫、目標庫版本三者必須一致。自行編譯 SQL 驅動插件是解決 MySQL 庫衝突的標準做法，亦適用於 PostgreSQL、ODBC、SQLite 等其他驅動。