mysqlclient 安裝失敗問題排查與解決方案（Linux 服務器）
聲明：使用 ChatGPT 整理，內容僅供參考。
一、問題背景
在 Linux 服務器虛擬環境中執行以下命令時出現錯誤：
pip install -r requirements.txt
報錯信息核心如下：
pkg-config: not found
Can not find valid pkg-config name.
Specify MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS env vars manually
最終導致：
Getting requirements to build wheel did not run successfully
二、問題本質原因
mysqlclient 是一個 C 擴展庫，在安裝時需要
本機編譯，而你的系統環境中缺少以下關鍵組件：
| 依賴組件 | 作用 |
|---|---|
| pkg-config | 用於查找 MySQL/MariaDB 庫的編譯參數 |
| MySQL 開發頭文件 | 提供 mysql C API |
| GCC / Make | 編譯 C 擴展 |
因此 pip 在編譯 mysqlclient 時 無法定位 MySQL 的開發庫，直接失敗。
三、適用系統説明
該問題常見於：
- Ubuntu Server
- Debian
- Docker 基礎鏡像
- 極簡 Linux 系統
桌面版系統一般不會出現此問題（依賴已預裝）。
四、標準解決方案（Ubuntu / Debian 系）
1️⃣ 安裝系統依賴
sudo apt update
sudo apt install -y pkg-config default-libmysqlclient-dev build-essential
2️⃣ 重新安裝 mysqlclient
pip install mysqlclient
# 或
pip install -r requirements.txt
五、RHEL / CentOS / AlmaLinux 系解決方案
sudo dnf install -y mysql-devel pkgconfig gcc python3-devel
pip install mysqlclient
六、Docker 環境解決方案
Dockerfile 中加入：
RUN apt update && apt install -y pkg-config default-libmysqlclient-dev build-essential
然後重新構建鏡像即可。
七、為什麼一定要安裝這些依賴？
mysqlclient 並不是純 Python 包，其核心是：
- MySQL 官方 C 客户端接口封裝
- 性能遠優於 PyMySQL
- 是 Django 官方推薦驅動
所以必須提前準備好 C 編譯環境 + MySQL 開發頭文件。
八、常見錯誤對照表
報錯信息 原因
pkg-config: not found 未安裝 pkg-config
Can not find valid pkg-config name 未安裝 mysql/mariadb 開發庫
Python.h not found 未安裝 python3-dev
gcc: command not found 未安裝 gcc
九、最終確認清單
執行以下命令確認環境完整：
pkg-config --version
mysql_config --version
gcc --version
全部正常後即可確保 mysqlclient 能成功安裝。
十、結論
✅ 該問題不是 pip 錯誤
✅ 是系統缺少 mysqlclient 編譯依賴
✅ 安裝開發庫後即可永久解決
✅ 適合集成到生產服務器和 Docker 構建流程中
📌 適用於：Django + MySQL + mysqlclient 生產級部署環境
