PHP源码数据库连接失败问题排查与解决方法

使用PHP源码搭建环境后，数据库连接失败是非常常见的现象。请不要急于怀疑代码本身存在错误——绝大多数情况下，问题出在环境配置、权限设置、PHP扩展或服务状态这几个环节中的某一处没有正确对应。关键不在于盲目猜测，而在于依照逻辑顺序逐一排查：先让错误信息暴露出具体原因，再逐层深入验证。

立即捕获真实错误信息

连接失败时不要忽略错误提示。在使用 mysqli_connect() 或 new PDO() 后，务必立即添加错误输出代码：

• mysqli：if (!$conn) { echo "错误：" . mysqli_connect_error(); exit; }
• PDO：用 try-catch 包裹，catch (PDOException $e) { echo $e->getMessage(); }

通过常见的错误信息可以快速定位问题根源：

• Connection refused → MySQL 服务未启动，或者 3306 端口被防火墙拦截
• Access denied for user → 用户名或密码错误，或者 'user'@'host' 的组合与授权表不匹配
• Unknown MySQL server host → host 值拼写错误、DNS 解析失败、容器名称写错
• No such file or directory → 使用 localhost 时走 Unix socket 失败，换成 127.0.0.1 通常可以解决

确认MySQL服务真正在运行且监听正确

使用一键集成环境（如 phpStudy、XAMPP）时，不要被控制面板上的“绿色图标”所迷惑——它亮着并不代表服务进程真的正常存活：

• 打开控制面板，确认 MySQL 的状态显示为“已启动”；若启动失败，点击“日志”查看 mysql_error.log，里面会记录具体的故障原因
• 通过命令行验证：Windows 执行 netstat -ano | findstr :3306，Linux/macOS 执行 ss -tlnp | grep 3306，检查 3306 端口是否处于 LISTEN 状态
• 检查 my.cnf 或 my.ini 配置文件：确保没有设置 skip-networking，并且 bind-address = 127.0.0.1 或 0.0.0.0（不要只设为 ::1，否则 IPv4 连接会失败）

核对连接参数与用户授权细节

账号密码正确并不代表一定能够连接。MySQL 的用户授权基于“user”@“host”这个组合，必须完全匹配：

• 登录 MySQL 后执行：SELECT User, Host FROM mysql.user;，确认你使用的用户对应的 Host 究竟是 localhost、127.0.0.1 还是 %
• 本地开发环境建议统一使用 127.0.0.1，强制走 TCP 协议，避免 localhost 因 socket 文件路径问题产生歧义
• 如果是 Docker 环境或远程连接，用户 Host 必须写成具体的 IP 或者 %，然后执行授权：GRANT ALL ON your_db.* TO 'user'@'%' IDENTIFIED BY 'pass'; FLUSH PRIVILEGES;

检查PHP扩展是否启用且版本兼容

即便连接参数完全正确，如果 pdo_mysql 或 mysqli 这两个扩展没有被启用，连接第一步就会失败：

• 运行 php -m | grep -i pdo（Linux/macOS）或 php -m（Windows 手动查找），确认 pdo、pdo_mysql、mysqli 都在输出列表中
• 如果使用 Laravel，它额外要求 ctype、json、mbstring 扩展；Symfony 需要 intl 扩展；Laravel 10+ 要求 PHP ≥ 8.1，版本过低连框架本身都无法运行
• MySQL 8.0 及以上版本默认采用 caching_sha2_password 认证插件，PHP 7.4 及以下版本不支持此协议，需要手动更改：执行 ALTER USER 'user'@'%' IDENTIFIED WITH mysql_native_password BY 'pass'; FLUSH PRIVILEGES;