PHP数据库连接失败排查指南

当PHP连接MySQL失败时，问题十有八九不在代码本身，而是隐藏在环境配置、权限控制或网络架构的细微之处：从MySQL服务是否可达、host填写localhost还是127.0.0.1引发的socket/TCP路径差异，到MySQL 8+认证插件不兼容、Docker中localhost指向错误、SELinux/firewalld拦截、用户host匹配逻辑陷阱，再到多版本PHP下mysqli扩展未真正加载——每一步都可能无声“卡死”连接。本文提供一套分层验证法：先用命令行mysql命令快速判断底层连通性，再逐层排查网络、权限、配置与运行时环境，直击那些不报错却让人抓狂的真实痛点，帮你把“Connection refused”“Access denied”“mysqli_connect()返回false”等模糊报错，精准定位到一行配置、一个用户定义或一次服务重启。

mysqli_connect() 返回 false 时怎么快速定位

绝大多数 mysqli_connect() 失败不是代码写错，而是环境配置或权限问题。先别急着改 PHP 代码，直接在命令行验证 MySQL 服务是否可达：

mysql -h 127.0.0.1 -P 3306 -u root -p

常见干扰项包括：

• mysqli_connect() 的第 2 个参数（host）填 localhost 会走 socket 文件，填 127.0.0.1 才走 TCP —— 两者权限可能不同
• PHP 进程用户（如 www-data）没权限读取 socket 文件（/var/run/mysqld/mysqld.sock），此时强制用 IP 地址绕过
• MySQL 8+ 默认禁用 mysql_native_password 插件，而旧版 PHP 驱动不支持 caching_sha2_password，需显式指定：

  $conn = mysqli_connect($host, $user, $pass, $db, $port, null, MYSQLI_CLIENT_SSL);

  或改用户认证方式

pdo\_mysql 报 “SQLSTATE[HY000] [2002] Connection refused”

这个错误明确指向连接被拒，和 DNS、防火墙、bind-address 配置强相关。重点检查：

• MySQL 配置中 bind-address 是否为 127.0.0.1 或 0.0.0.0 —— 若是 127.0.0.1，外部容器或远程 PHP 就连不上
• Docker 场景下，PHP 容器里用 localhost 指向的是它自己，不是宿主机的 MySQL；应改用宿主机网关（如 host.docker.internal）或 Docker 网络别名
• SELinux 或 firewalld 开启时，即使端口监听着，也可能拦截连接；临时关闭验证：

  sudo setenforce 0

连接成功但查询报 “Access denied for user”

这说明认证通过了，但权限不足。MySQL 用户权限是 host + user 组合决定的，'root'@'localhost' 和 'root'@'%' 是两个完全不同的账号。

执行以下语句确认当前匹配的用户：

SELECT USER(), CURRENT_USER();

USER() 是你登录时声明的用户，CURRENT_USER() 是 MySQL 实际匹配到的账号 —— 如果两者不一致，说明权限没落在你预期的 host 上。

修复建议：

• 创建用户时明确指定 host：

  CREATE USER 'app'@'172.16.0.%' IDENTIFIED BY 'pwd';

• 不要依赖 GRANT ALL ON *.*，按最小权限原则授权：

  GRANT SELECT, INSERT ON mydb.* TO 'app'@'172.16.0.%';

• 修改后必须 FLUSH PRIVILEGES;，否则不生效

phpinfo() 显示 mysqlnd 已启用但 mysqli 扩展仍不可用

常见于多版本 PHP 共存环境（如 Ubuntu 同时装了 php7.4 和 php8.1）。php -v 和 phpinfo() 可能对应不同 CLI / FPM 实例。

验证实际加载的扩展路径：

php -r "echo ini_get('extension_dir');"

然后检查该目录下是否存在 mysqli.so（Linux）或 php_mysqli.dll（Windows），再确认对应 php.ini 是否启用了它：

extension=mysqli

特别注意：

• CLI 和 Web SAPI（如 Apache mod_php 或 php-fpm）使用不同 php.ini 文件，修改后需重启对应服务
• Ubuntu/Debian 下，php-mysql 包已被弃用，应安装 php-mysqlnd
• 某些云主机（如阿里云轻量）默认禁用 mysqli，需手动开启并重启 php-fpm

真正卡住人的，往往不是语法错误，而是 MySQL 用户的 host 匹配逻辑、PHP 加载的其实是另一个 php.ini、或者 Docker 网络里 localhost 指向了错误的地址 —— 这些地方不打日志、不报具体原因，只能靠分层验证。

到这里，我们也就讲完了《PHP数据库连接失败排查指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！