phpMyAdmin 連線 MySQL 失敗常見原因與解決方案全攻略

phpMyAdmin 顯示「嘗試連接到 MySQL 伺服器，但伺服器拒絕連接」是開發環境配置中最常見的問題之一。本文系統梳理從配置檢查、服務狀態、權限設定到網路層面的完整排查流程，並針對 Windows (WAMP/XAMPP)、Linux、Docker 等環境提供針對性解決方案。

錯誤訊息解讀

phpMyAdmin 嘗試連接到 MySQL 伺服器，但伺服器拒絕連接。
您應該檢查 config.inc.php 中的主機、用戶名和密碼，
並且確定這些信息與 MySQL 服務器的管理員所給出的信息一致。

這是通用錯誤訊息，實際原因可能包含：

• MySQL 服務未啟動或異常停止
• 連線參數錯誤（主機、埠、Socket、帳號、密碼）
• MySQL 使用者權限/主機限制
• 防火牆/SELinux 阻擋
• Socket 檔案路徑不匹配（Linux 常見）
• MySQL 綁定地址配置錯誤

快速診斷清單（按優先序）

1. 確認 MySQL 服務狀態

# Linux systemd
systemctl status mysqld
# 或
systemctl status mysql

# Windows 服務
net start mysql
# 或服務管理器 services.msc 查找 MySQL

# Docker
docker ps | grep mysql
docker logs   # 查看啟動日誌

關鍵日誌特徵：正常啟動會出現 ready for connections；若出現 InnoDB: Starting shutdown、Shutdown complete 則服務已停止。

2. 驗證 config.inc.php 連線參數

<?php
// phpMyAdmin 設定檔典型位置
// /etc/phpmyadmin/config.inc.php (Linux)
// C:\wamp64\apps\phpmyadminX.X.X\config.inc.php (Windows)

$cfg['Servers'][$i]['host'] = '127.0.0.1';  // 建議用 IP 而非 localhost
$cfg['Servers'][$i]['port'] = '3306';       // 確認埠號
$cfg['Servers'][$i]['socket'] = '';         // Linux 若用 Socket 需指定正確路徑
$cfg['Servers'][$i]['user'] = 'root';
$cfg['Servers'][$i]['password'] = 'your_password';
$cfg['Servers'][$i]['auth_type'] = 'cookie'; // 或 config/http
?>

關鍵差異：localhost 在 PHP 中預設使用 Unix Socket 連線；127.0.0.1 強制使用 TCP/IP。Windows 環境下兩者皆走 TCP，但 Linux 下若 Socket 路徑錯誤，localhost 會失敗而 127.0.0.1 可能成功。

3. 測試命令列連線（隔離 phpMyAdmin 問題）

# 基本連線測試
mysql -h 127.0.0.1 -P 3306 -u root -p

# 指定 Socket (Linux)
mysql -S /var/run/mysqld/mysqld.sock -u root -p

# 免密碼測試 (僅限本地 root 無密碼)
mysql -u root

若命令列能連線，問題在 phpMyAdmin 設定；若命令列也失敗，問題在 MySQL 服務/權限/網路。

4. 檢查 MySQL 使用者權限與主機限制

-- 登入 MySQL 後執行
SELECT User, Host, plugin, authentication_string FROM mysql.user;

-- 常見問題：root 只允許 localhost 連線
-- 解決：建立允許 127.0.0.1 或 % 的使用者
CREATE USER 'admin'@'127.0.0.1' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON *.* TO 'admin'@'127.0.0.1' WITH GRANT OPTION;
FLUSH PRIVILEGES;

-- MySQL 8.0+ 需指定驗證插件
CREATE USER 'admin'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'strong_password';

5. 檢查 MySQL 綁定地址配置

# /etc/mysql/mysql.conf.d/mysqld.cnf 或 /etc/my.cnf
[mysqld]
# 預設只監聽 127.0.0.1，若需外部連線改為 0.0.0.0
bind-address = 127.0.0.1
# 或
bind-address = 0.0.0.0

# 修改後必須重啟
systemctl restart mysqld

6. 防火牆與 SELinux（Linux 環境）

# firewalld
firewall-cmd --permanent --add-service=mysql
firewall-cmd --reload

# iptables
iptables -A INPUT -p tcp --dport 3306 -j ACCEPT

# SELinux 允許 httpd 連線資料庫
setsebool -P httpd_can_network_connect_db 1

環境特定解決方案

Windows (WAMP/XAMPP) 環境

1. 服務未啟動：WAMP 圖示呈橙/紅色 → 右鍵啟動所有服務
2. 埠號衝突：3306 被佔用 → 修改 my.ini 中 port=3307，同步更新 phpMyAdmin 設定
3. 密碼遺忘：參考下方重設 root 密碼
4. 啟動腳本路徑問題：原文提到的 start mysql -l localhost -u root -p 參數錯誤，正確為 mysql -h localhost -u root -p（無 -l 參數）

Docker 環境

# docker-compose.yml 關鍵設定
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: mydb
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
    command: --default-authentication-plugin=mysql_native_password

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    environment:
      PMA_HOST: mysql        # 服務名稱而非 localhost
      PMA_PORT: 3306
      PMA_USER: root
      PMA_PASSWORD: rootpass
    ports:
      - "8080:80"
    depends_on:
      - mysql

關鍵點：容器間通訊使用服務名稱 mysql，而非 localhost。

重設 MySQL Root 密碼（通用方法）

# 1. 停止服務
systemctl stop mysqld

# 2. 跳過權限表啟動
mysqld_safe --skip-grant-tables --skip-networking &

# 3. 免密登入並修改
mysql -u root
FLUSH PRIVILEGES;
ALTER USER 'root'@'localhost' IDENTIFIED BY 'new_password';
# MySQL 5.7 或較舊版本
UPDATE mysql.user SET authentication_string=PASSWORD('new_password') WHERE User='root';
FLUSH PRIVILEGES;
EXIT;

# 4. 正常重啟
pkill mysqld
systemctl start mysqld

進階除錯技巧

啟用 MySQL 一般查詢日誌

[mysqld]
general_log = 1
general_log_file = /var/log/mysql/general.log
log_output = FILE

觀察 phpMyAdmin 實際發送的連線請求與錯誤碼。

PHP 錯誤日誌

<?php
// 臨時測試腳本 test_conn.php
$mysqli = new mysqli('127.0.0.1', 'root', 'password', '', 3306);
if ($mysqli->connect_errno) {
    echo "連線失敗: " . $mysqli->connect_error;
    echo "錯誤碼: " . $mysqli->connect_errno;
} else {
    echo "連線成功";
    $mysqli->close();
}
?>

常見 MySQL 錯誤碼對照

總結檢查順序

1. MySQL 服務是否運行？
2. 命令列能否連線？
3. phpMyAdmin config.inc.php 參數是否正確（特別是 host 用 127.0.0.1）？
4. MySQL 使用者是否允許從該主機連線？
5. 防火牆/SELinux 是否阻擋？
6. 埠號/ Socket 路徑是否匹配？

按順序排查，90% 以上案例可在前三步解決。記住：先驗證 MySQL 本身，再檢查 phpMyAdmin 設定，避免在應用層浪費時間。