在 Ubuntu 环境里，PHP-FPM 启动正常，但页面一到数据库连接就报错，这类问题往往最耗时间的不是修复本身，而是不清楚该先查哪一层。与其反复改代码，不如按“PHP 扩展、MySQL 服务、连接参数、用户权限、网络与 PHP-FPM/Nginx 通信”这条链路逐项核对，基本都能定位到原因。

先确认 PHP 是否装了 MySQL 扩展

这是最常见、也最容易被忽略的一类问题。代码本身没有问题，但 PHP 运行环境缺少对应的 MySQL 扩展时，数据库连接自然会直接失败。

如果你当前使用的是 PHP 8.1，那么需要安装的扩展就是 php8.1-mysql。安装完成后，还必须重启 PHP-FPM 服务，否则新扩展不会生效。

php8.1-mysql

这里的关键点不在“有没有装”，而在“装完有没有重启 PHP-FPM”。很多排查卡住，往往就卡在这一步。

检查 MySQL 服务是否正常运行，以及监听地址是否正确

第二类高频原因是 MySQL 本身没有启动，或者虽然启动了，但当前监听方式不支持你的连接请求。

先看服务状态

可以先执行下面的命令查看 MySQL 是否在运行：

sudo systemctl status mysql

如果服务没有启动，再手动拉起：

sudo systemctl start mysql

再核对 bind-address 配置

MySQL 的配置文件通常位于 /etc/mysql/mysql.conf.d/mysqld.cnf。其中 bind-address 决定了服务监听范围：

• 只允许本地访问时，设置为 127.0.0.1
• 需要允许远程连接时，设置为 0.0.0.0

如果这里配置不符合实际部署方式，PHP 端的连接就会失败。

重点核对数据库连接参数

当服务和扩展都没问题后，最值得仔细检查的就是连接信息本身。主机名、用户名、密码、数据库名，只要有一项不对，就会直接报错。

不要忽视 localhost 和 127.0.0.1 的差异

localhost 和 127.0.0.1 看起来接近，但实际连接路径可能不同。如果 MySQL 当前只监听 Unix socket，那么改成 IP 地址后反而可能失败。

逐项对照代码配置

建议把代码中的 mysqli_connect() 或 PDO 配置逐项核对一遍，重点确认：

• 主机名是否与 MySQL 实际监听方式一致
• 用户名和密码是否拼写正确
• 数据库名是否真实存在

这一步虽然基础，但也是最常见的出错点之一。

连接信息正确时，再查 MySQL 用户权限

如果主机名、账号密码和库名都确认无误，仍然无法连接，就要怀疑 MySQL 用户权限不足。也就是用户存在，但没有访问目标数据库的权限。

这时可以使用 root 账户登录 MySQL，执行授权命令：

GRANT ALL PRIVILEGES ON database_name.* TO 'username'@'host' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

这里要特别注意，命令里的 host 必须和 PHP 代码实际使用的主机名一致，例如 localhost。如果代码里写的是本地连接，而权限授权给了别的来源地址，连接依旧会失败。

跨服务器部署时，别漏掉防火墙和 3306 端口

如果 PHP-FPM 和 MySQL 不在同一台服务器上，那么问题就不再只是应用配置，还会涉及网络连通性。MySQL 默认端口是 3306，一旦防火墙未放行，PHP 发出的请求就到不了数据库。

在 Ubuntu 中，可以使用下面的命令开放端口：

sudo ufw allow 3306

这一步通常只在远程连接场景下才重要，但一旦漏掉，表现出来就会像“数据库怎么都连不上”。

有时不是数据库问题，而是 Nginx 与 PHP-FPM 通信异常

有些“数据库连接失败”并不是 MySQL 真连不上，而是请求根本没被正确交给 PHP-FPM 处理。只要 PHP-FPM 本身异常，Nginx 就无法把 PHP 请求转发下去，最终表面现象也可能像数据库报错。

先检查 PHP-FPM 服务状态

sudo systemctl status phpX.X-fpm

再检查 fastcgi_pass 与 socket 路径是否一致

需要确认 Nginx 配置中的 fastcgi_pass，是否与 PHP-FPM 实际使用的 socket 文件一致，例如：

/var/run/php/php8.1-fpm.sock

除了路径本身，socket 文件权限也不能忽略。Nginx 用户通常是 www-data，它必须有权限访问这个 socket，否则请求无法转发到 PHP-FPM。

高并发下还要看 PHP-FPM 进程池参数

如果前面几项都没问题，但故障只在访问量上来时出现，那么就该看 PHP-FPM 的进程池配置了。

当 pm.max_children 设置过低时，在高并发场景下所有子进程会被占满，新请求无法及时处理，最终表现为连接超时或失败。

这个参数需要结合服务器的 CPU 和内存资源来调整。原文给出的示例值是 50。修改后，记得重启 PHP-FPM，使配置生效。

一条更省时间的排查顺序

如果你不想在多个配置文件之间来回切换，可以直接按下面的顺序检查：

1. 先确认 PHP 是否安装了对应版本的 MySQL 扩展
2. 检查 MySQL 服务是否启动，bind-address 是否符合访问方式
3. 核对 mysqli_connect() 或 PDO 中的主机名、用户名、密码、数据库名
4. 确认 MySQL 用户是否拥有目标数据库权限
5. 如果是跨服务器部署，再检查 3306 端口和防火墙
6. 最后排查 PHP-FPM 与 Nginx 的通信，以及 pm.max_children 是否过低

按这个顺序处理，通常能比“哪里报错改哪里”更快定位到真正的问题。