PHP-FPM未加载mysqli扩展是Class "mysqli" not found的最常见原因；需确认php -m输出含mysqli、编辑对应版本php.ini启用extension=mysqli、安装php*-mysqli包并重启PHP-FPM与Nginx服务。
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'。
立即学习“PHP免费学习笔记（深入）”；
- 先用
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 扩展的底层兼容性——这两者不匹配时，错误不会立刻暴露，排查成本最高。
