Mac 解決 localhost 無法連接 MySQL：Socket vs TCP 差異詳解

現象

Mac 上 PHP 使用 localhost 連接 MySQL 失敗，錯誤訊息含 No such file or directory；改用 127.0.0.1 或本機 IP 即正常。Java、命令列工具用 localhost 卻正常。

根本原因：Socket vs TCP

PHP 預設讀取 php.ini 中的 mysql.default_socket、mysqli.default_socket、pdo_mysql.default_socket，若與 MySQL 實際 Socket 路徑不一致，連接失敗。

排查步驟

# 1. 查看 MySQL 實際 Socket 路徑
mysql -u root -p -e "SHOW VARIABLES LIKE 'socket';"
# 或
mysql -u root -p -e "STATUS;" | grep Socket

# 2. 查看 PHP 設定的 Socket 路徑
php -i | grep default_socket
# 輸出範例：
# mysql.default_socket => /var/mysql/mysql.sock
# mysqli.default_socket => /var/mysql/mysql.sock
# pdo_mysql.default_socket => /var/mysql/mysql.sock

解決方案

方案 A：修改 PHP 設定（推薦）

# 編輯 php.ini（確認路徑：php --ini）
sudo vim /etc/php.ini

# 修改三處為 MySQL 實際 Socket 路徑（如 /tmp/mysql.sock）
mysql.default_socket = /tmp/mysql.sock
mysqli.default_socket = /tmp/mysql.sock
pdo_mysql.default_socket = /tmp/mysql.sock

# 重啟 Apache/PHP-FPM
sudo apachectl restart
# 或
sudo brew services restart php

方案 B：修改 MySQL 設定

# 編輯 my.cnf
sudo vim /etc/my.cnf

[mysqld]
socket = /var/mysql/mysql.sock  # 改為 PHP 預期路徑

# 重啟 MySQL
sudo mysql.server restart

方案 C：建立軟連結（快速臨時修復）

sudo mkdir -p /var/mysql
sudo ln -s /tmp/mysql.sock /var/mysql/mysql.sock

方案 D：程式碼中強制使用 TCP

// PDO
$dsn = "mysql:host=127.0.0.1;dbname=test;charset=utf8mb4";

// mysqli
$db = new mysqli('127.0.0.1', 'user', 'pass', 'dbname', 3306);

驗證

php -r "new PDO('mysql:host=localhost;dbname=test', 'user', 'pass'); echo 'OK';"

補充：為什麼 Java/命令列正常？

• Java JDBC 驅動預設使用 TCP（jdbc:mysql://localhost:3306/ 實際解析為 127.0.0.1）。
• MySQL Client (mysql) 可透過 --protocol=socket 或 --protocol=tcp 指定，預設嘗試 Socket 失敗會回退 TCP。

結語

localhost 在 MySQL 協定中強制走 Unix Socket，而 127.0.0.1 強制走 TCP。Mac 因多版本 MySQL 共存（Homebrew、官方 DMG、MAMP、系統預設）導致 Socket 路徑不一致是常見問題。建議統一使用 127.0.0.1 或在部署腳本中自動對齊 Socket 路徑，避免環境差異導致的連接失敗。