数据库连接失败需依次检查配置、服务状态、权限与网络、调试模式及PHP扩展：核对host/port/账号/库名；确认MySQL服务运行并监听端口；验证用户授权主机和防火墙；开启框架调试获取详细错误；确保pdo_mysql等扩展已启用且认证兼容。
如果您在使用PHP框架时遇到数据库连接失败的问题，通常是因为数据库配置信息不正确或数据库服务未正常运行。以下是排查和修复此问题的具体方法：
一、检查数据库配置文件
PHP框架通常将数据库连接参数集中存放在配置文件中（如 Laravel 的 .env 文件、ThinkPHP 的 database.php 或 CodeIgniter 的 database.php）。确认这些参数是否与实际数据库环境完全匹配。
1、打开框架对应的数据库配置文件，定位到数据库主机、端口、用户名、密码、数据库名等字段。
2、核对 host 值是否为本地地址（如 127.0.0.1）或远程服务器IP，而非 localhost（部分系统下 localhost 会强制走 socket 连接）。
立即学习“PHP免费学习笔记（深入）”；
3、确认 port 值是否与数据库服务实际监听端口一致（MySQL 默认为 3306，PostgreSQL 默认为 5432）。
4、验证 用户名和密码是否具备对应数据库的登录权限，且未被误输入空格或特殊字符。
5、检查数据库名是否拼写正确，并确认该数据库已在数据库服务中真实创建。
二、验证数据库服务状态
即使配置无误，若数据库服务未启动或崩溃，PHP 仍无法建立连接。需直接在服务器层面确认数据库进程是否活跃并监听指定端口。
1、通过 SSH 登录服务器，执行 systemctl status mysql（Ubuntu/Debian）或 systemctl status mysqld（CentOS/RHEL）查看 MySQL 服务状态。
2、若服务未运行，执行 systemctl start mysql 启动服务。
3、使用 netstat -tuln | grep :3306 检查 3306 端口是否处于 LISTEN 状态。
4、尝试用命令行客户端直连：执行 mysql -h 127.0.0.1 -P 3306 -u 用户名 -p，输入密码后观察是否可成功进入 MySQL 提示符。
三、测试数据库用户权限与网络可达性
某些部署环境下，数据库用户可能仅允许从特定主机连接，或防火墙策略阻止了 PHP 所在服务器与数据库之间的通信。
1、登录数据库服务器，执行 SELECT host, user FROM mysql.user; 查看当前用户的允许访问主机列表。
2、若显示 host 为 localhost，而 PHP 应用运行在 Docker 容器或另一台机器，则需执行 CREATE USER '用户名'@'%' IDENTIFIED BY '密码'; 并授权。
3、在 PHP 所在服务器上运行 telnet 数据库IP 3306 或 nc -zv 数据库IP 3306，确认端口可通。
4、检查服务器防火墙设置，确保数据库端口未被 iptables、ufw 或云平台安全组规则拦截。
四、启用框架数据库调试模式
多数现代 PHP 框架支持开启数据库查询日志与异常详细输出，有助于定位底层连接拒绝的具体原因（如 Access denied、Connection refused、Timeout 等）。
1、在 Laravel 中，将 APP_DEBUG=true 和 DB_LOG_QUERIES=true 设置于 .env 文件，并清空缓存：php artisan config:clear。
2、在 ThinkPHP 中，修改 app_debug = true 并确保 show_error_msg = true 开启，同时检查 runtime/log 目录下数据库错误日志。
3、在 CodeIgniter 中，将 $db['default']['db_debug'] = TRUE; 设为 true，并确认 error_reporting(E_ALL) 已启用。
4、触发一次数据库操作（如模型查询），观察浏览器或日志中输出的完整 PDOException 或 mysqli_connect_error 信息。
五、检查 PHP 扩展与驱动兼容性
PHP 必须加载对应数据库的扩展（如 pdo_mysql、mysqli、pdo_pgsql），且版本需与数据库协议兼容；缺失或版本错配将导致连接函数根本不可用。
1、在命令行执行 php -m | grep -i mysql，确认 pdo_mysql 和 mysqli 是否已列出。
2、若未出现，编辑 php.ini，取消 extension=pdo_mysql 和 extension=mysqli 行前的分号注释，并重启 Web 服务（如 apache2 或 php-fpm）。
3、运行 php --ri pdo_mysql 查看扩展编译版本及支持的客户端库版本。
4、对比数据库服务器版本（如 MySQL 8.0+ 默认使用 caching_sha2_password 认证插件），确认 PHP 扩展是否支持；必要时在数据库中为用户重置认证方式：ALTER USER '用户名'@'%' IDENTIFIED WITH mysql_native_password BY '密码';。
