解決 PHP 無法連接 MySQL 但命令行操作正常的問題

在開發或維護 PHP 應用時，常會遇到一種情況：PHP 腳本無法連接 MySQL 資料庫，但使用命令行工具卻能正常登入並操作資料庫。這通常是因為 PHP 使用的 MySQL Socket 路徑與實際運行的 MySQL 服務不一致所導致。本文將詳細說明如何排查並解決這個問題。

故障現象

PHP 網頁顯示資料庫連接失敗錯誤（如 Can't connect to local MySQL server through socket），但在終端機下執行 mysql -u root -p 卻能順利登入並執行 SQL 指令。

解決步驟

1. 確認 MySQL 實際使用的 Socket 路徑

在命令行登入 MySQL 後，執行以下指令查看目前的 socket 設定：

SHOW VARIABLES LIKE 'socket';

輸出範例：

+---------------+----------------------------+
| Variable_name | Value                      |
+---------------+----------------------------+
| socket        | /home/mysql/data/mysql.sock |
+---------------+----------------------------+

記下 Value 欄位的路徑（本例為 /home/mysql/data/mysql.sock），這是 PHP 需要使用的正確 socket 路徑。

2. 修改 php.ini 設定

打開 PHP 設定檔 php.ini（通常位於 /etc/php.ini、/usr/local/php/etc/php.ini 或透過 php --ini 查找），搜尋 mysql.default_socket 參數。

預設值通常為空（註解狀態），需將其設為上一步取得的路徑：

; Default socket name for local MySQL connects.
; If empty, uses the built-in MySQL defaults.
mysql.default_socket = /home/mysql/data/mysql.sock

注意：若使用的是 PHP 7+ 且透過 mysqli 或 PDO_MySQL 連接，還需同步設定 mysqli.default_socket 和 pdo_mysql.default_socket 為相同路徑。

3. 重啟 PHP 服務

修改完成後，必須重啟 PHP 服務使設定生效：

• PHP-FPM：systemctl restart php-fpm 或 service php-fpm restart
• Apache 模組模式：systemctl restart httpd 或 service apache2 restart
• Nginx + PHP-FPM：重啟 php-fpm 即可

驗證修復

建立一個簡單的 PHP 測試腳本 test_conn.php：

<?php
$mysqli = new mysqli("localhost", "root", "your_password", "test_db");
if ($mysqli->connect_errno) {
    echo "連接失敗: " . $mysqli->connect_error;
} else {
    echo "連接成功！Server 版本: " . $mysqli->server_info;
    $mysqli->close();
}
?>

在瀏覽器訪問該檔案，若顯示「連接成功！」即表示問題已解決。

常見誤區與補充

• Socket vs Port：若 PHP 使用 127.0.0.1 而非 localhost 連接，會走 TCP/IP 協定（預設端口 3306），繞過 socket 機制，可作為臨時替代方案。
• 多版本 MySQL 共存：伺服器若安裝多個 MySQL 實例，務必確認 PHP 連接的是正確實例的 socket。
• 權限問題：確保 PHP 運行用戶（如 www-data、nginx）對 socket 檔案所在目錄有讀取/執行權限。