MySQL-Python 安裝避坑指南：從 libmysqlclient 缺失到跨平台編譯失敗的完整解決方案

前言

MySQL-Python（即 MySQLdb）作為 Python 連接 MySQL 的經典驅動，雖已停止維護（推薦改用 mysqlclient 或 PyMySQL），但在大量存量項目中仍不可避免。本文匯總 CentOS、Ubuntu、Windows 下常見安裝失敗場景，提供經實戰驗證的解決方案。

核心依賴：系統級開發包

無論何種安裝方式，必須先安裝 MySQL 客戶端開發庫，提供 mysql_config、頭文件（mysql.h、my_config.h）及動態庫（libmysqlclient.so）。

常見錯誤與解決方案

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

原因：動態鏈接器找不到 MySQL 客戶端庫，常見於手動編譯安裝 MySQL 或非標準路徑。

解決：

# 1. 確認庫文件位置
find / -name "libmysqlclient*"

# 2. 建立軟鏈接到系統庫路徑
ln -sf /usr/local/mysql/lib/libmysqlclient*.so* /usr/lib64/
# 或 /usr/lib/ 視架構而定

# 3. 更新動態鏈接器緩存
ldconfig

# 4. 驗證
ldd /path/to/_mysql.so | grep mysql

或設置環境變量（臨時/永久）：

export LD_LIBRARY_PATH=/usr/local/mysql/lib:$LD_LIBRARY_PATH
echo "/usr/local/mysql/lib" > /etc/ld.so.conf.d/mysql.conf && ldconfig

錯誤 2：mysql_config not found / EnvironmentError: mysql_config not found

原因：setup.py 依賴 mysql_config 獲取編譯參數，但其不在 PATH 中。

解決：

# 1. 定位 mysql_config
which mysql_config
# 或
find / -name mysql_config

# 2. 修改 site.cfg（源碼包根目錄）
# 取消註釋並指定路徑
mysql_config = /usr/bin/mysql_config
# 或
mysql_config = /usr/local/mysql/bin/mysql_config

# 3. 或設置環境變量安裝
export MYSQL_CONFIG=/usr/local/mysql/bin/mysql_config
pip install MySQL-python

錯誤 3：gcc 編譯失敗：my_config.h / mysql.h 找不到

原因：缺少 MySQL 開發包頭文件。

解決：安裝對應開發包（見上表），確認頭文件存在：

ls /usr/include/mysql/mysql.h
ls /usr/include/mysql/my_config.h

錯誤 4：Ubuntu easy_install/pip 安裝報 command 'gcc' failed with exit status 1

完整解決流程：

# 1. 安裝構建工具鏈與 Python 開發頭文件
apt-get update
apt-get install -y build-essential python3-dev libmysqlclient-dev

# 2. 推薦使用 mysqlclient（MySQL-Python 的維護分支，支持 Python 3）
pip install mysqlclient

# 3. 若必須用 MySQL-python（Python 2 專用）
pip install MySQL-python==1.2.5

CentOS 7 實戰完整記錄

[root@centos7 ~]# yum install -y mysql-devel gcc python3-devel
[root@centos7 ~]# pip3 install mysqlclient
Collecting mysqlclient
  Downloading mysqlclient-2.1.1.tar.gz (89 kB)
Building wheels for collected packages: mysqlclient
  Building wheel for mysqlclient (setup.py) ... done
Successfully installed mysqlclient-2.1.1

[root@centos7 ~]# python3 -c "import MySQLdb; print(MySQLdb.__version__)"
2.1.1

Windows 環境特殊處理

Windows 無原生編譯環境，推薦使用預編譯 Wheel：

# 1. 從 https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient 下載對應版本 .whl
# 如：mysqlclient-2.1.1-cp39-cp39-win_amd64.whl

# 2. 安裝
pip install mysqlclient-2.1.1-cp39-cp39-win_amd64.whl

或使用純 Python 實現的 PyMySQL 避免編譯依賴：

pip install PyMySQL
# 代碼中兼容：
import pymysql
pymysql.install_as_MySQLdb()

現代替代方案推薦

總結

MySQL-Python 安裝失敗 90% 歸因於 缺少系統級 MySQL 開發包 或 mysql_config 路徑未正確指定。遵循「先裝開發包 → 確認 mysql_config → 再 pip install」流程，配合現代驅動替代，可徹底消除安裝焦慮。