您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

PHP PDO_MySQL 擴展安裝全指南：Linux 源碼編譯、Windows DLL 配置、故障排查

編輯：PHP 相關知識

PDO_MySQL 是 PHP 連接 MySQL 的**現代標準介面** (支援預處理、事務、多種獲取模式)。本文涵蓋 Linux 手動編譯安裝、Windows 擴展啟用、常見「could not find driver」故障根因與解決方案。

方法一：Linux 手動編譯安裝 (通用、可控版本)

適用於未使用包管理器、需指定 PHP/MySQL 路徑、或需特定版本的場景。

1. 下載源碼包

# 官方 PECL 下載頁：https://pecl.php.net/package/PDO_MYSQL
wget https://pecl.php.net/get/PDO_MYSQL-1.0.2.tgz  # 選擇對應 PHP 版本的包
tar -zxvf PDO_MYSQL-1.0.2.tgz
cd PDO_MYSQL-1.0.2

**注意：** PHP 7.4+ 內建 `pdo_mysql` 通常無需單獨安裝 PECL 包，**直接編譯 PHP 時 `--with-pdo-mysql` 即可**。本節針對舊版本或動態擴展場景。

2. phpize 準備編譯環境

# 指定目標 PHP 的 phpize 路徑 (關鍵！多 PHP 版本共存時)
/usr/local/php/bin/phpize

# 輸出應顯示：
# Configuring for:
# PHP Api Version: 20190902
# Zend Module Api No: 20190902
# Zend Extension Api No: 320190902

3. 配置編譯參數 (核心步驟)

./configure \
  --with-php-config=/usr/local/php/bin/php-config \
  --with-pdo-mysql=/usr/local/mysql   # MySQL 安裝根目錄 (含 include/lib)

常見錯誤： `configure: error: Cannot find MySQL header files`

解決： 建立 MySQL 頭文件軟連結至系統目錄：

ln -s /usr/local/mysql/include/* /usr/local/include/
# 或指定具體路徑
./configure --with-pdo-mysql=/usr/local/mysql --with-mysql-sock=/tmp/mysql.sock

4. 編譯安裝

make -j$(nproc)
make install
# 輸出提示安裝路徑，如：
# Installing shared extensions: /usr/local/php/lib/php/extensions/no-debug-non-zts-20190902/

5. 啟用擴展 (php.ini)

; 1. 確認 extension_dir 指向上述安裝目錄 (或將 .so 複製到統一目錄)
extension_dir = "/usr/local/php/lib/php/extensions/"

; 2. 載入擴展 (Linux 下無 php_ 前綴，後綴 .so)
extension=pdo_mysql.so

; 3. 重啟 PHP-FPM / Apache
systemctl restart php-fpm
# 或
/usr/local/php/sbin/php-fpm -t && kill -USR2 `cat /usr/local/php/var/run/php-fpm.pid`

6. 驗證

php -m | grep pdo_mysql
php -r "print_r(PDO::getAvailableDrivers());"

方法二：Windows 環境啟用 (php.ini 配置)

Windows 版 PHP **內建 `php_pdo_mysql.dll`**，通常只需啟用。

1. 修改 php.ini

; 確認 extension_dir 指向 ext 目錄
extension_dir = "C:/php/ext"  ; 根據實際路徑修改

; 啟用核心擴展 (順序無關，但建議先載入 pdo)
extension=php_pdo.dll
extension=php_pdo_mysql.dll
extension=php_mysqlnd.dll  ; 推薦使用 mysqlnd 驅動 (PHP 5.3+ 內建)

2. 關鍵依賴：`libmysql.dll` / `libmysqlnd.dll` 必須在系統 PATH 中

**這是 Windows 下「could not find driver」90% 的根因。**

PHP 載入 `php_pdo_mysql.dll` 時需動態鏈接 MySQL 客戶端庫。

解決方案二選一：

推薦：將 PHP 安裝目錄加入系統環境變量 PATH (需重啟 Apache/命令行生效)。
備選：將 `libmysql.dll` (或 `libmysqlnd.dll`) 複製到 `C:/Windows/System32/` 或 Apache `bin/` 目錄下 (無需重啟系統，重啟 Apache 即可)。

PHP 7.4+ 通常使用 `mysqlnd` (原生驅動)，無需外部 `libmysql.dll`。若仍報錯，檢查 `phpinfo()` 中 `PDO drivers` 是否顯示 `mysql`。

3. 重啟 Apache 驗證

httpd -k restart
# 或在 XAMPP/WAMP 面板重啟

常見故障排查速查表

現象	可能原因	解決方案
`PDOException: could not find driver`	擴展未載入 / `libmysql.dll` 缺失	檢查 `php -m`、`phpinfo()`；Windows 加 PATH 或複製 DLL
`PDO::__construct(): MySQL server has gone away`	連接超時 / `wait_timeout` 過短	設置 `PDO::ATTR_PERSISTENT => true` 或調大 MySQL `wait_timeout`
編譯報錯 `mysql.h not found`	MySQL 開發包未裝 / 路徑錯誤	`yum install mysql-devel` / `apt install libmysqlclient-dev`；指定 `--with-pdo-mysql=路徑`
`sql_mode=only_full_group_by` 報錯	MySQL 5.7+ 預設嚴格模式	PDO 屬性 `PDO::MYSQL_ATTR_INIT_COMMAND => "SET sql_mode=''"`
預處理失效 (模擬預處理)	`ATTR_EMULATE_PREPARES` 預設 true	設置 `$pdo->setAttribute(PDO::ATTR_EMULATE_PREPARES, false);`

現代最佳實踐：直接編譯 PHP 時內建

**新部署環境強烈建議：** 编譯 PHP 時直接啟用，避免動態擴展版本不匹配、維護成本高。

./configure \
  --prefix=/usr/local/php \
  --with-pdo-mysql=mysqlnd \  # 使用內建 mysqlnd，無需外部 MySQL 庫
  --with-mysqli=mysqlnd \
  --with-mysql-sock=/tmp/mysql.sock \
  ...其他參數
make && make install

優點：零依賴、效能最優 (mysqlnd 非阻塞、內存管理優化)、版本強一致性。

驗證腳本 (通用)

<?php
try {
    $pdo = new PDO("mysql:host=127.0.0.1;dbname=test;charset=utf8mb4", 'user', 'pass', [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES => false,
    ]);
    echo "PDO_MySQL 連接成功！驅動: " . $pdo->getAttribute(PDO::ATTR_DRIVER_NAME) . "\n";
    echo "可用驅動: " . implode(', ', PDO::getAvailableDrivers()) . "\n";
} catch (PDOException $e) {
    die("連接失敗: " . $e->getMessage());
}
?>

掌握安裝原理與依賴鏈，PDO_MySQL 部署將不再是攔路虎。