PHP 连接 MySQL 失败怎么办？从账号权限到端口设置逐项检查

PHP程序突然无法连接MySQL，表面上看只是一个数据库连接错误，实际可能涉及数据库服务、账号权限、网络端口、PHP扩展以及连接参数等多个环节。排查这类问题最忌讳一次修改多个配置，否则即使问题消失，也很难知道究竟是哪一项发生了作用。

更有效的方法是从最基础的连接条件开始，一层层确认数据库服务、账号、端口、PHP环境和网络配置是否正常。

首先确认MySQL服务是否正常运行

在排查PHP之前，应该先确认MySQL服务器本身正在运行。如果数据库服务没有启动，PHP端无论使用mysqli还是PDO，都不可能建立连接。

Linux服务器可以通过系统服务管理工具检查MySQL或MariaDB的运行状态。例如：

sudo systemctl status mysql

如果服务器使用MariaDB，则服务名称可能是：

sudo systemctl status mariadb

也可以使用MySQL客户端直接测试：

mysql -u username -p -h 127.0.0.1

如果命令行本身就无法连接，那么问题还没有进入PHP层面，应先解决数据库服务、账号或网络问题。

确认数据库用户名、密码和数据库名称

数据库连接通常需要主机地址、用户名、密码和数据库名称四项信息。任何一项填写错误，都可能导致连接失败。

尤其需要注意MySQL账号的一个重要特性：MySQL用户实际上是由“用户名＋主机”共同确定的。

例如：

'appuser'@'localhost'
'appuser'@'127.0.0.1'
'appuser'@'%'

虽然用户名都是appuser，但它们并不是完全相同的账号授权对象。

因此，如果PHP程序使用127.0.0.1连接，而数据库授权只针对localhost配置，就可能出现权限问题。

可以使用具有管理权限的账号查看现有用户：

SELECT User, Host FROM mysql.user;

如果确实需要允许远程服务器连接，则应针对实际应用服务器的IP地址授予必要权限，而不是为了省事直接开放给所有来源。

例如：

CREATE USER 'appuser'@'192.168.1.10' IDENTIFIED BY 'password';
GRANT SELECT, INSERT, UPDATE, DELETE ON database_name.* TO 'appuser'@'192.168.1.10';

对于生产环境，没有必要为了方便直接使用：

'appuser'@'%'

开放所有来源。过于宽泛的数据库授权会增加安全风险。

检查MySQL监听的端口

MySQL默认端口通常是3306，但实际服务器不一定使用这个端口。

可以在MySQL配置文件中检查：

[mysqld]
port=3306

如果数据库使用其他端口，PHP连接时必须填写正确的端口。

mysqli可以这样写：

$conn = new mysqli(
'127.0.0.1',
'username',
'password',
'database',
3308
);

PDO则可以写成：

$pdo = new PDO(
'mysql:host=127.0.0.1;port=3308;dbname=database;charset=utf8mb4',
'username',
'password'
);

这里还有一个容易混淆的问题：localhost和127.0.0.1并不一定完全等价。

在Linux环境中，localhost通常可能通过Unix Socket连接，而127.0.0.1则通过TCP连接。如果其中一种方式无法连接，可以尝试另一种方式，这有助于判断问题究竟出现在Socket还是TCP连接层面。

检查MySQL的监听地址

如果PHP和MySQL运行在不同服务器上，仅仅知道数据库端口还不够，还需要确认MySQL是否监听外部网络接口。

例如：

bind-address = 127.0.0.1

意味着MySQL主要监听本机回环地址，远程服务器通常无法直接连接。

如果业务确实需要远程数据库连接，则需要根据服务器架构调整监听地址，并同时配置防火墙、数据库账号授权和云平台安全规则。

但不应该为了让程序“先连上”就简单地把数据库暴露到公网。更安全的方式是通过私有网络、VPN或严格限制来源IP等方式建立数据库访问通道。

检查防火墙和云安全组

如果数据库运行在云服务器上，连接链路可能同时受到操作系统防火墙和云平台安全组的限制。

例如服务器使用3306端口，必须确保实际需要访问数据库的服务器能够到达该端口。

可以使用：

nc -vz 192.168.1.20 3306

测试TCP连接。

如果返回连接被拒绝，可能意味着MySQL没有监听该地址或端口，或者防火墙阻止了连接。

如果连接一直超时，则更应该检查网络路径、防火墙和云安全组。

不建议为了测试方便直接向公网开放3306端口。数据库端口属于高价值攻击目标，生产环境应该尽可能限制访问来源。

确认PHP已经安装MySQL扩展

如果MySQL服务正常、账号也正确，但PHP程序仍然无法连接，就需要检查PHP环境。

可以通过：

php -m

查看是否存在：

mysqli
pdo_mysql

如果程序使用mysqli，就必须确保mysqli扩展可用；如果程序使用PDO，则需要确认pdo_mysql扩展已经安装。

例如Ubuntu系统通常可以安装：

sudo apt install php-mysql

安装之后需要根据实际运行环境重启PHP-FPM或Web服务器。

需要特别注意，命令行PHP和网站使用的PHP版本可能不是同一个环境。命令行执行php -m显示已经安装，并不一定意味着Apache或PHP-FPM使用的PHP也加载了相同扩展。

因此，遇到这种情况最好通过phpinfo()或者服务器实际PHP配置进一步确认。

使用正确的连接代码

mysqli的基本连接方式可以写成：

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$conn = new mysqli(
'127.0.0.1',
'username',
'password',
'database'
);

$conn->set_charset('utf8mb4');

PDO则可以采用异常模式：

$pdo = new PDO(
'mysql:host=127.0.0.1;dbname=database;charset=utf8mb4',
'username',
'password',
[
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION
]
);

这里推荐使用utf8mb4，而不是简单写utf8。对于现代中文网站以及需要保存完整Unicode字符的应用，utf8mb4通常更加合适。

不要把“数据库连接失败”和“SQL查询失败”混为一谈

数据库连接成功，并不代表后面的SQL一定能够执行。

例如：

$conn = new mysqli(
'127.0.0.1',
'username',
'password',
'database'
);

如果这一阶段失败，应该检查服务器、账号、密码、端口和网络。

如果连接成功，但执行：

$result = $conn->query($sql);

之后出现错误，则应该转而检查SQL语句、数据表、字段名称以及当前数据库账号是否拥有相应操作权限。

这两个阶段必须分开判断，否则很容易把SQL语法错误误认为数据库连接错误。

遇到“Access denied”应该重点检查什么

如果错误信息类似：

Access denied for user

通常应该优先检查用户名、密码以及账号的Host授权。

例如：

'appuser'@'localhost'

和：

'appuser'@'192.168.1.10'

可能拥有完全不同的权限。

如果错误类似：

Can't connect to MySQL server

则更应该检查MySQL服务是否运行、主机地址、端口、bind-address、防火墙以及网络连通性。

如果出现：

Unknown database

则通常说明数据库名称不存在或者连接参数中的数据库名称填写错误。

日志是定位复杂故障的重要依据

当基础检查无法解决问题时，应进一步查看MySQL和PHP的错误日志。

不同Linux发行版以及不同安装方式的日志路径可能不同，因此不能假定所有服务器都使用同一个固定路径。

PHP-FPM、Apache和Nginx也可能分别记录自己的错误信息。

生产环境中应该保留必要的错误日志，但不要直接把数据库用户名、密码、连接字符串等敏感信息输出到网页。开发阶段可以记录详细错误，正式网站则应该向用户显示简洁的错误提示，把具体诊断信息写入受保护的服务器日志。

连接超时和连接数问题需要单独处理

如果程序偶尔能够连接，偶尔出现连接失败，则问题可能不再是简单的用户名或密码错误。

这时候应该检查MySQL最大连接数、PHP-FPM进程数量、数据库连接持续时间以及服务器整体负载。

不要把PDO持久连接简单当成解决高并发问题的万能方案。持久连接在某些场景下有用，但也可能增加数据库连接管理复杂度。实际项目应该根据应用架构和数据库负载进行测试，而不是仅仅因为“连接慢”就启用持久连接。

正确的排查顺序比盲目修改配置更重要

PHP无法连接MySQL时，可以按照这样的顺序排查：

MySQL服务是否运行；数据库主机和端口是否正确；用户名和密码是否正确；MySQL账号的Host授权是否匹配；PHP是否加载mysqli或pdo_mysql；MySQL是否监听正确的网络地址；防火墙和云安全组是否允许连接；最后再检查PHP、Web服务器和MySQL日志。

如果PHP和MySQL位于同一台服务器，通常应该优先检查本机服务、账号授权、Socket或TCP连接以及PHP扩展。如果两者位于不同服务器，则还必须增加网络、防火墙和安全组检查。

数据库连接问题看起来复杂，但只要按照“服务、账号、地址、端口、权限、PHP环境、网络、日志”的顺序逐项排除，通常都可以比较快地找到真正的故障点。对于生产环境，更重要的是避免为了临时解决问题而扩大数据库权限或直接开放公网端口，否则一个看似普通的连接故障，可能最终演变成严重的安全问题。