PHP 问题解决：解决 "PDOException: SQLSTATE[HY000] [2002] No such file or directory" 错误

在 PHP 开发过程中，使用 PDO 连接数据库时，你可能会遇到以下错误：

"PDOException: SQLSTATE[HY000] [2002] No such file or directory"

或者类似的变体：

"SQLSTATE[HY000] [2002] Connection refused"

这个错误通常表示 PHP 无法通过 Unix socket 或 TCP 连接到 MySQL 数据库。本文将详细介绍该错误的常见原因，并提供原创的解决方案。

📌 错误示例

try {
    $pdo = new PDO('mysql:host=localhost;dbname=test', $username, $password);
} catch (PDOException $e) {
    echo "Connection failed: " . $e->getMessage();
}

🧩 常见原因分析

1. 使用 localhost 导致 Unix socket 连接失败

当使用 host=localhost 时，PDO 默认尝试通过 Unix socket 连接，但如果 socket 文件不存在或路径错误，就会报错。

2. MySQL 服务未运行

MySQL 数据库服务没有启动，导致无法建立连接。

3. Socket 文件路径配置错误

系统中的 MySQL socket 文件路径与 PDO 期望的路径不匹配。

4. 网络连接问题

在远程连接时，防火墙或网络配置阻止了连接。

5. MySQL 配置限制

MySQL 可能配置了连接限制或绑定了特定的 IP 地址。

✅ 解决方法

✅ 方法一：使用 127.0.0.1 替代 localhost

将连接字符串中的 localhost 改为 127.0.0.1，强制使用 TCP 连接：

try {
    $pdo = new PDO('mysql:host=127.0.0.1;dbname=test', $username, $password);
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
    echo "Connection failed: " . $e->getMessage();
}

✅ 方法二：指定正确的 Unix socket 路径

如果必须使用 Unix socket 连接，需要指定正确的 socket 文件路径：

try {
    // 根据你的系统配置调整 socket 路径
    $pdo = new PDO('mysql:unix_socket=/var/run/mysqld/mysqld.sock;dbname=test', $username, $password);
    
    // 常见的 socket 路径：
    // /var/run/mysqld/mysqld.sock (Debian/Ubuntu)
    // /var/lib/mysql/mysql.sock (CentOS/RHEL)
    // /tmp/mysql.sock (macOS)
} catch (PDOException $e) {
    echo "Connection failed: " . $e->getMessage();
}

✅ 方法三：检查 MySQL 服务状态

在命令行中检查 MySQL 服务是否正在运行：

# Linux/macOS
sudo service mysql status
# 或
sudo systemctl status mysql

# macOS (使用 Homebrew)
brew services list | grep mysql

# Windows
net start | find "MySQL"

如果服务未运行，启动它：

# Linux/macOS
sudo service mysql start
# 或
sudo systemctl start mysql

# macOS (使用 Homebrew)
brew services start mysql

✅ 方法四：创建数据库连接配置类

封装数据库连接逻辑，提供多种连接方式：

class DatabaseConnection {
    private $config;
    
    public function __construct($config) {
        $this->config = $config;
    }
    
    public function connect() {
        $attempts = [
            // 尝试 TCP 连接
            function() {
                $dsn = "mysql:host={$this->config['host']};port={$this->config['port']};dbname={$this->config['database']}";
                return new PDO($dsn, $this->config['username'], $this->config['password']);
            },
            
            // 尝试指定 socket 连接
            function() {
                if (isset($this->config['socket'])) {
                    $dsn = "mysql:unix_socket={$this->config['socket']};dbname={$this->config['database']}";
                    return new PDO($dsn, $this->config['username'], $this->config['password']);
                }
                return null;
            },
            
            // 回退到 127.0.0.1
            function() {
                $dsn = "mysql:host=127.0.0.1;port={$this->config['port']};dbname={$this->config['database']}";
                return new PDO($dsn, $this->config['username'], $this->config['password']);
            }
        ];
        
        foreach ($attempts as $attempt) {
            try {
                $pdo = $attempt();
                if ($pdo) {
                    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
                    return $pdo;
                }
            } catch (PDOException $e) {
                continue; // 尝试下一种连接方式
            }
        }
        
        throw new Exception("Unable to connect to database");
    }
}

// 使用示例
$config = [
    'host' => 'localhost',
    'port' => 3306,
    'database' => 'test',
    'username' => 'root',
    'password' => 'password',
    'socket' => '/var/run/mysqld/mysqld.sock'
];

try {
    $db = new DatabaseConnection($config);
    $pdo = $db->connect();
    echo "Connected successfully";
} catch (Exception $e) {
    echo "Connection failed: " . $e->getMessage();
}

✅ 方法五：调试连接问题

创建一个调试函数来检查连接参数：

function debugDatabaseConnection($host, $port, $database, $username) {
    echo "Debugging database connection:\n";
    echo "Host: $host\n";
    echo "Port: $port\n";
    echo "Database: $database\n";
    echo "Username: $username\n";
    
    // 检查端口是否开放
    $connection = @fsockopen($host, $port, $errno, $errstr, 5);
    if ($connection) {
        echo "Port $port is open on $host\n";
        fclose($connection);
    } else {
        echo "Port $port is closed on $host: $errstr\n";
    }
    
    // 检查 MySQL socket（如果使用 localhost）
    if ($host === 'localhost') {
        $commonSockets = [
            '/var/run/mysqld/mysqld.sock',
            '/var/lib/mysql/mysql.sock',
            '/tmp/mysql.sock',
            '/usr/local/var/mysql/mysql.sock'
        ];
        
        foreach ($commonSockets as $socket) {
            if (file_exists($socket)) {
                echo "Found MySQL socket: $socket\n";
            }
        }
    }
}

// 使用示例
debugDatabaseConnection('localhost', 3306, 'test', 'root');

✅ 方法六：检查 MySQL 配置

检查 MySQL 的配置文件（通常是 my.cnf 或 my.ini）中的绑定地址设置：

# my.cnf
[mysqld]
bind-address = 0.0.0.0  # 允许所有 IP 连接
# 或
bind-address = 127.0.0.1  # 仅允许本地连接

🧰 推荐开发实践

📝 总结

希望这篇原创文章能帮助你彻底解决 PHP 中数据库连接的 "No such file or directory" 问题！如果你还有其他 PHP 相关疑问，欢迎继续提问。