PHP 測試 MySQL 連線腳本：快速排查資料庫連接失敗原因

使用場景

部署 CMS、框架專案時，常遇到「資料庫連線失敗」但不確定是 PHP 環境、帳號密碼、主機位址、防火牆、或 MySQL 服務本身的問題。一個獨立測試腳本能在 10 秒內定位故障來源。

測試腳本 test_db.php

<?php
/**
 * PHP MySQL 連線測試
 * 用法：修改下方參數，放入網站根目錄，瀏覽器訪問或 CLI 執行
 */
$host   = 'localhost';   // MySQL 主機 IP 或域名
$user   = 'root';        // 資料庫使用者
$pass   = '123';         // 密碼
$dbname = 'test';        // 選填：指定資料庫名稱

// 1. 建立連線 (mysqli 物件導風格，支援錯誤異常)
$mysqli = @new mysqli($host, $user, $pass, $dbname);

if ($mysqli->connect_errno) {
    // 連線失敗
    echo "<h3 style='color:red'>❌ 連線失敗</h3>";
    echo "<p>錯誤碼： {$mysqli->connect_errno}</p>";
    echo "<p>錯誤訊息： {$mysqli->connect_error}</p>";
    echo "<hr><h4>常見原因排查：</h4>";
    echo "<ul>";
    echo "<li>主機位址錯誤 (localhost vs 127.0.0.1 vs 實際 IP)</li>";
    echo "<li>使用者名稱/密碼錯誤</li>";
    echo "<li>MySQL 服務未啟動 (systemctl status mysqld / net start mysql)</li>";
    echo "<li>防火牆阻擋 3306 埠</li>";
    echo "<li>MySQL 未授權該主機存取 (GRANT ... ON *.* TO 'user'@'%' ...)</li>";
    echo "<li>PHP 未安裝 mysqli / pdo_mysql 擴展 (php -m | grep mysql)</li>";
    echo "</ul>";
    exit;
}

// 2. 連線成功
echo "<h3 style='color:green'>✅ 連線成功！</h3>";
echo "<p>Server version: {$mysqli->server_info}</p>";
echo "<p>Host: {$mysqli->host_info}</p>";
echo "<p>Protocol: {$mysqli->protocol_version}</p>";

// 3. 簡單查詢驗證權限
$result = $mysqli->query("SELECT VERSION() as ver, CURRENT_USER() as usr, DATABASE() as db");
if ($row = $result->fetch_assoc()) {
    echo "<table border='1' cellpadding='5'>";
    echo "<tr><th>MySQL 版本</th><td>{$row['ver']}</td></tr>";
    echo "<tr><th>當前用戶</th><td>{$row['usr']}</td></tr>";
    echo "<tr><th>預設資料庫</th></td><td>{$row['db']}</td></tr>";
    echo "</table>";
}
$mysqli->close();
?>

進階版：支援 PDO 與命令列參數

<?php
// test_db_advanced.php
$dsn = 'mysql:host=localhost;dbname=test;charset=utf8mb4';
$user = 'root';
$pass = '123';

try {
    $pdo = new PDO($dsn, $user, $pass, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]);
    echo "PDO 連線成功\n";
    $stmt = $pdo->query("SELECT VERSION()");
    echo "Version: " . $stmt->fetchColumn() . "\n";
} catch (PDOException $e) {
    echo "PDO 連線失敗: " . $e->getMessage() . "\n";
    exit(1);
}
?>

CLI 快速測試

# 直接執行
php test_db.php

# 或單行指令 (mysqli)
php -r '$m=new mysqli("localhost","root","123"); echo $m->connect_errno?"Fail: ".$m->connect_error:"OK";'

常見錯誤碼對照表

總結

將此腳本收藏至工具箱，遇到資料庫連線問題第一時間執行，能立即區分是「程式碼配置錯誤」還是「環境/權限問題」，大幅縮短除錯時間。