PHP 連接 MySQL 失敗「Can't connect to MySQL server on localhost」完整排查手冊

錯誤現象

PHP 應用拋出錯誤編號 2003：Can't connect to MySQL server on localhost (10061)，表示客戶端無法建立到 MySQL 服務端的 TCP 連接。

核心原因分析

分類解決方案

場景一：虛擬主機/共享主機用戶

1. 聯繫空間商確認 MySQL 服務狀態
2. 核對配置文件中的主機地址：是否為 localhost、127.0.0.1 或特定 Socket 路徑
3. 檢查是否達到空間商限制的並發連接數上限

場景二：獨立主機/雲服務器用戶（擁有 Root 權限）

步驟 1：驗證服務狀態

Windows：services.msc → 找到 MySQL → 狀態應為「正在運行」；或命令行 sc query mysql

Linux：systemctl status mysqld 或 service mysql status；若未運行執行 service mysql start

步驟 2：檢查磁碟空間

df -h  # Linux
# 關注 /var/lib/mysql 掛載點，剩餘空間應 > 10%

空間不足時清理舊日志、臨時文件或擴容磁碟。

步驟 3：核對 my.ini/my.cnf 關鍵配置

[mysqld]
basedir = C:/mysql-5.7  # 安裝目錄，需與實際一致
datadir = C:/mysql-5.7/data  # 數據目錄
port = 3306
bind-address = 0.0.0.0  # 允許遠程連接，本地只需 127.0.0.1
skip-name-resolve  # 禁用 DNS 反解，加快連接（見避坑指南）

修改後必須 service mysql restart 生效。

步驟 4：Windows 高併發優化 - 調整 TcpTimedWaitDelay

現象：高併發短連接導致大量 TIME_WAIT 佔用端口，新連接建立失敗。

解決：修改註冊表 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

• 新建 DWORD 值 TcpTimedWaitDelay（默認 240 秒）
• 設為 30~60（十進制），建議 30
• 重啟系統生效

進階排查技巧

• 測試連通性：telnet 127.0.0.1 3306 或 mysql -h127.0.0.1 -uroot -p（強制 TCP 而非 Socket）
• 查看錯誤日志：tail -f /var/log/mysqld.log 定位具體啟動失敗原因
• 檢查權限表：確認 mysql.user 表中存在 'root'@'localhost' 和 'root'@'127.0.0.1' 賬號

避坑指南

關於 skip-name-resolve：開啟後 MySQL 不再進行 DNS 反向解析，連接速度顯著提升，但會導致 'user'@'localhost' 賬號無法匹配（解析為 'user'@'127.0.0.1'）。
對策：同步創建 'user'@'127.0.0.1' 賬號並授權，或保留 localhost 解析並在 hosts 文件中硬編碼 127.0.0.1 localhost。

總結檢查清單

1. 服務是否運行？
2. 磁碟空間是否充足？
3. 配置文件路徑、端口、綁定地址是否正確？
4. 防火牆/安全組是否放行 3306？
5. Windows 高併發是否調整 TcpTimedWaitDelay？
6. 錯誤日志是否有異常堆棧？

按順序排查，90% 的 2003 錯誤可在 5 分鐘內定位解決。