PHPEnv下PHP无法连接MySQL的Nginx配置排查

本文深入剖析了在PHPEnv环境下PHP无法连接MySQL的四大核心原因：PHP-FPM未加载mysqli扩展导致“Class 'mysqli' not found”、MySQL用户host匹配失败引发的“Access denied”认证问题、Nginx与PHP-FPM间Unix socket权限及路径不一致造成的静默连接失败，以及MySQL 8.0+默认caching_sha2_password认证插件与旧版PHP mysqli扩展不兼容带来的隐蔽超时或空白页现象——每一种都附带精准诊断命令、配置修改要点和实操修复步骤，帮你绕过表层错误直击底层机制，快速定位并彻底解决看似简单却极易陷入排查死循环的数据库连接顽疾。

PHP-FPM 未加载 mysqli 扩展导致 Class "mysqli" not found

这是最常被忽略的底层原因：Nginx 本身不解析 PHP，它把请求交给 PHP-FPM 处理；而 PHP-FPM 进程若没启用 mysqli 扩展，new mysqli() 就会直接报错，连连接参数都还没走到验证阶段。

典型错误日志：PHP Fatal error: Uncaught Error: Class "mysqli" not found，出现在 /var/log/nginx/error.log 或 /var/log/php8.1-fpm.log 中。

• 确认当前 PHP 版本：php -v（比如输出 PHP 8.1.27）
• 检查扩展是否启用：php -m | grep mysqli —— 若无输出，说明未加载
• 编辑对应版本的配置文件，如 /etc/php/8.1/fpm/php.ini，确保这行存在且未被注释：extension=mysqli
• 安装缺失扩展（Debian/Ubuntu）：sudo apt install php8.1-mysqli；CentOS/RHEL 用 sudo yum install php-mysqlnd
• 重启服务：sudo systemctl restart php8.1-fpm nginx

MySQL 用户 host 匹配失败导致 Access denied for user 'root'@'localhost'

PHP 脚本运行在 FPM 进程里，看似“本地”，但 MySQL 对 'root'@'localhost' 和 'root'@'127.0.0.1' 视为两个完全不同的用户——前者走 Unix socket，后者走 TCP。而 localhost 在 mysqli 连接中默认强制走 socket，一旦 socket 文件路径不对或权限受限，就会静默 fallback 失败。

常见表现：命令行 mysql -u root -p 能进，但 PHP 死活连不上，且错误里明确带 @'localhost'。

• 先用 127.0.0.1 强制走 TCP 测试：$conn = new mysqli('127.0.0.1', 'root', 'your_pass', 'users');
• 登录 MySQL 查看实际用户绑定：SELECT User, Host FROM mysql.user WHERE User = 'root';
• 若只有 'root'@'localhost'，但你用 127.0.0.1 连，就需补一条：CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY 'your_pass'; GRANT ALL ON *.* TO 'root'@'127.0.0.1'; FLUSH PRIVILEGES;
• 更稳妥做法是统一用 'root'@'%'（仅限内网环境），并确保防火墙未放行外网 3306 端口

Nginx + PHP-FPM 权限与 socket 路径不一致

当 Nginx 配置中 fastcgi_pass 指向的是 Unix socket（如 fastcgi://unix:/run/php/php8.1-fpm.sock），而 PHP-FPM 实际监听的 socket 文件权限或属组不匹配，会导致 PHP 脚本能执行、但无法完成数据库连接所需的系统级调用（比如读取 MySQL socket 文件）。

典型现象：页面空白或 500 错误，error.log 里没有 mysqli 报错，但 mysqli_connect_error() 返回空字符串或超时。

• 确认 PHP-FPM socket 文件真实路径：grep -r "listen =" /etc/php/8.1/fpm/pool.d/www.conf（常见为 /run/php/php8.1-fpm.sock）
• 检查该 socket 文件权限：ls -l /run/php/php8.1-fpm.sock，属组应为 www-data（Ubuntu）或 nginx（CentOS），且权限至少为 srw-rw----
• 确认 Nginx worker 进程用户与 socket 属组一致：ps aux | grep nginx 看主进程用户，再查 cat /etc/nginx/nginx.conf | grep user
• 必要时在 PHP-FPM pool 配置中显式设置：listen.owner = www-data、listen.group = www-data、listen.mode = 0660

MySQL 8.0+ 默认认证插件不兼容老 PHP 版本

MySQL 8.0 开始默认用 caching_sha2_password 插件，而 PHP 7.4 及更早的 mysqli 扩展不支持它——结果就是用户名密码完全正确，连接也“成功”返回，但后续任何查询都卡住或报错，mysqli_connect_error() 却返回空。

错误日志可能含：Authentication plugin 'caching_sha2_password' cannot be loaded，或干脆没日志，只在浏览器看到空白页。

• 检查当前 root 用户用的什么插件：SELECT user, host, plugin FROM mysql.user WHERE user = 'root';
• 临时修复（开发环境可用）：ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_pass'; FLUSH PRIVILEGES;
• 长期方案：升级 PHP 到 8.0+，或编译安装时加 --with-mysql-sock 并确保 OpenSSL 支持完整
• 连接前加一句避免卡死：mysqli_options($conn, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

真正卡点不在代码写法，而在 MySQL 用户的 plugin 字段和 PHP 扩展的底层兼容性——这两者不匹配时，错误不会立刻暴露，排查成本最高。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。