Linux 下編譯鏈接 MySQL C API 程式，最穩健的方式是使用官方提供的 mysql_config 腳本自動輸出編譯器標誌與鏈接器參數，避免手動拼湊路徑導致的版本不匹配、庫缺失、ABI 衝突等疑難雜症。
gcc -o myapp myapp.c $(mysql_config --cflags --libs)
# C++ 專案
g++ -o myapp myapp.cpp $(mysql_config --cflags --libs)
mysql_config 會根據安裝前綴自動展開為類似：
-I/usr/include/mysql -L/usr/lib64/mysql -lmysqlclient -lpthread -lz -lm -lrt -lssl -lcrypto -ldl
| 選項 | 用途 | 典型輸出示例 |
|---|---|---|
--cflags | 編譯器標誌：包含路徑、宏定義、優化選項 | -I/usr/include/mysql -D_GNU_SOURCE |
--include | 僅包含路徑 (不含宏)，--cflags 涵蓋此功能 | -I/usr/include/mysql |
--libs | 鏈接器參數：庫路徑、客戶端庫、系統依賴庫 | -L/usr/lib64/mysql -lmysqlclient -lpthread -lz -lm -lrt -lssl -lcrypto -ldl |
--libs_r | 執行緒安全版客戶端庫 (舊版區分，新版已合併) | 同 --libs |
--plugindir | 插件目錄 (認證插件等) | /usr/lib64/mysql/plugin |
--version | 顯示 mysql_config 版本及對應 MySQL 版本 | mysql_config Ver 1.0 for MySQL 8.0.33 |
--port / --socket | 預設連接埠 / Unix socket 路徑 | 3306 / /var/lib/mysql/mysql.sock |
# RPM/DEB 安裝典型路徑
gcc -o myapp myapp.c \
-I/usr/include/mysql \
-L/usr/lib64/mysql \
-lmysqlclient -lpthread -lz -lm -lrt -lssl -lcrypto -ldl
# 源碼安裝典型路徑 (prefix=/usr/local/mysql)
gcc -o myapp myapp.c \
-I/usr/local/mysql/include \
-L/usr/local/mysql/lib \
-lmysqlclient -lpthread -lz -lm -lrt -lssl -lcrypto -ldl
⚠️ 庫順序鐵律：-lmysqlclient 必須置於依賴庫 (-lpthread -lz ...) 之前，否則鏈接器報 undefined reference to `mysql_init' 等符號缺失。
| 錯誤現象 | 根因 | 解決 |
|---|---|---|
fatal error: mysql.h: No such file or directory | 頭文件路徑缺失 | 確認 mysql_config --cflags 包含正確 -I 路徑 |
undefined reference to `mysql_real_connect' | 鏈接順序錯或缺庫 | 將 -lmysqlclient 前置；補充 -lssl -lcrypto (MySQL 8.0+ 強制 SSL) |
/usr/bin/ld: cannot find -lmysqlclient | 庫路徑錯誤 | 檢查 mysql_config --libs 中 -L 路徑；ldconfig -p | grep mysqlclient 驗證 |
運行時 libmysqlclient.so.21: cannot open shared object file | 動態庫搜尋路徑缺失 | export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64/mysql 或寫入 /etc/ld.so.conf.d/mysql.conf 執行 ldconfig |
交叉編譯報 architecture mismatch | 宿主/目標架構混用 | 使用目標工具鏈 arm-linux-gnueabihf-gcc 搭配目標板 mysql_config (或交叉編譯產出的) |
cmake_minimum_required(VERSION 3.10)
project(MySQLDemo LANGUAGES C)
# 查找 MySQL (FindMySQL.cmake 內建於 CMake 3.14+)
find_package(MySQL REQUIRED)
add_executable(myapp main.c)
target_link_libraries(myapp PRIVATE MySQL::mysqlclient)
# 自動處理包含目錄、鏈接庫、編譯定義、執行緒標誌
優勢：跨平台、IDE 友好、自動傳播依賴、支援 target_compile_features 設定 C 標準。
pkg-config --cflags --libs mysqlclient
# 輸出與 mysql_config 基本一致，適用於非 MySQL 官方發佈版 (如 MariaDB、Percona)
$(mysql_config --cflags --libs --static)
# 輸出包含 -static-libgcc 等，生成無動態依賴二進制，體積增大 ~2-3MB
# 注意：glibc 建議動態鏈接，靜態鏈接可能導致 DNS/NSS/權限功能異常
有 mysql_config 就用 mysql_config；
無則參考其輸出手動構造；
庫順序 -lmysqlclient 在前；
運行時 LD_LIBRARY_PATH 勿忘；
新專案優先 CMake find_package。
規範化編譯鏈接流程，讓 MySQL C API 開發從「編譯鬥爭」解脫，專注於業務邏輯實現。
