PHP数据库连接失败需依次检查：一、服务状态；二、连接参数；三、用户权限与主机绑定；四、防火墙及网络连通性；五、启用错误报告捕获具体异常。
如果PHP代码在运行时无法连接到数据库，则可能是由于数据库配置错误、服务未启动或网络限制等原因导致。以下是解决此问题的步骤：
一、检查数据库服务状态
确认数据库服务进程是否正在运行，是建立连接的前提条件。若服务未启动，PHP将无法与数据库建立任何通信。
1、登录服务器终端或命令行界面。
2、执行 systemctl status mysql（Linux系统使用MySQL）或 systemctl status mariadb 检查服务状态。
立即学习“PHP免费学习笔记（深入）”；
3、若显示 inactive 或 failed，运行 systemctl start mysql 启动服务。
4、对于Windows系统，打开“服务”管理器，查找 MySQL 或 MariaDB 服务，确认其状态为“正在运行”。
二、验证数据库连接参数
PHP脚本中使用的主机地址、端口、用户名、密码及数据库名必须与实际数据库配置完全一致，任一参数错误均会导致连接失败。
1、打开PHP连接代码文件，定位到 mysqli_connect() 或 new PDO() 调用处。
2、核对 $host 是否为本地地址（如 127.0.0.1 或 localhost），注意部分系统中 localhost 会强制走socket而非TCP。
3、确认 $port 值是否为数据库实际监听端口，默认MySQL为 3306，若修改过需同步更新。
4、检查 $username 和 $password 是否与数据库用户权限设置一致，特别注意空格或特殊字符未转义的情况。
三、确认数据库用户权限与主机绑定
MySQL/MariaDB默认创建的用户可能仅允许从特定主机（如 localhost）连接，而PHP脚本若通过网络访问（如Nginx+PHP-FPM分离部署），实际来源IP可能不被授权。
1、使用管理员账户登录数据库：mysql -u root -p。
2、执行查询：SELECT User, Host FROM mysql.user; 查看目标用户的Host字段值。
3、若目标用户Host为 localhost，但PHP运行环境IP为 192.168.1.100，则需授权：GRANT ALL ON database_name.* TO 'user'@'192.168.1.100' IDENTIFIED BY 'password';。
4、执行 FLUSH PRIVILEGES; 刷新权限表。
四、检查防火墙与网络连通性
即使数据库服务运行正常且参数无误，若中间存在防火墙拦截或路由不通，TCP连接仍会被拒绝或超时。
1、在PHP所在服务器上执行：telnet 127.0.0.1 3306（如未安装telnet，可用 nc -zv 127.0.0.1 3306 替代）。
2、若返回 Connection refused，说明数据库未监听该端口或绑定地址错误；若超时，则可能存在防火墙策略阻断。
3、检查系统防火墙：ufw status（Ubuntu）或 firewall-cmd --list-ports（CentOS），确认 3306/tcp 已放行。
4、若数据库位于远程服务器，还需确认云平台安全组规则是否开放对应端口。
五、启用PHP错误报告并捕获具体异常
默认情况下，PHP可能隐藏数据库连接错误细节，仅返回通用失败提示。开启详细错误输出可快速定位根本原因。
1、在PHP脚本开头添加：error_reporting(E_ALL); ini_set('display_errors', 1);。
2、若使用mysqli，将连接语句改为：$conn = mysqli_connect($host, $user, $pass, $db, $port) or die('Connect Error: ' . mysqli_connect_error());。
3、若使用PDO，确保构造时设置异常模式：$pdo = new PDO($dsn, $user, $pass, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);。
4、查看页面输出或PHP错误日志（如 /var/log/php_errors.log）中的具体错误信息，例如 Connection refused、Access denied 或 Unknown MySQL server host。
