MySQL-Python (mysqlclient) 安裝避坑全集：從缺庫到編譯失敗的標準化修復

MySQL-Python (mysqlclient) 安裝避坑全集：從缺庫到編譯失敗的標準化修復

mysqlclient（MySQL-Python 分支）是 Python 連接 MySQL 的主流 C 擴展。本文匯總 CentOS/Ubuntu/Windows 三大平台的高頻安裝錯誤（libmysqlclient_r.so 缺失、mysql_config not found、my_config.h 缺失、gcc 編譯失敗）及標準化修復腳本，涵蓋系統依賴、環境變量、site.cfg 配置、軟鏈接構建全流程。

錯誤一：ImportError: libmysqlclient_r.so.16: cannot open shared object file

原因：運行時找不到 MySQL 客戶端動態庫。

# 1. 修正 site.cfg 指向 mysql_config
# /path/to/mysqlclient/site.cfg
mysql_config = /usr/bin/mysql_config

# 2. 構建軟鏈接
ln -s /usr/local/mysql/lib/libmysqlclient* /usr/lib/
ldconfig

# 3. 驗證
python -c "import _mysql; print('OK')"

錯誤二：Ubuntu easy_install/pip 安裝報 gcc 失敗

錯誤三：CentOS pip install MySQL-python 缺 my_config.h/mysql.h

Windows 預編譯 Wheel 直裝
import MySQLdb
conn = MySQLdb.connect(host='localhost', user='root', passwd='pwd', db='test', charset='utf8mb4')
cur = conn.cursor()
cur.execute('SELECT VERSION()')
print(cur.fetchone())
cur.close()
conn.close()

最佳實踐清單

優先使用系統包管理器安裝 python3-mysqlclient（Debian/Ubuntu）或 mysql-devel（RHEL/CentOS），再 pip install mysqlclient。
生產環境鎖定版本 mysqlclient==2.1.1，避免突發破壞性更新。
虛擬環境隔離依賴，避免系統 Python 污染。
連接池推薦 DBUtils.PooledDB 或 SQLAlchemy engine.pool。