Laravel+MySQL环境Postman测试POST请求报SQLSTATE[HY000][2002]错误

两个报错均为PHP进程无法正常连接MySQL服务导致，不同报错对应不同的连接失败逻辑：

• 配置DB_HOST=127.0.0.1返回Connection Refused（连接被拒绝）：PHP走TCP协议连接3306端口时，目标端口无服务监听、端口不匹配或被防火墙拦截
• 配置DB_HOST=localhost返回No such file or directory（文件或目录不存在）：PHP走Unix域套接字文件连接MySQL时，配置的套接字文件路径与MySQL实际路径不匹配

1. 优先确认MySQL服务运行状态 #

执行以下命令检查MySQL/MariaDB服务状态：

# MySQL服务
systemctl status mysql
# MariaDB服务
systemctl status mariadb

• 若返回服务未启动，执行启动命令并设置开机自启：

systemctl start mysql
systemctl enable mysql

启动后重试连接，若仍报错继续往下排查。

2. 修复TCP连接被拒绝问题 #

• 执行命令查看MySQL实际监听的端口和地址：

netstat -tulpn | grep mysql

正常输出会显示监听地址（默认127.0.0.1或0.0.0.0）和监听端口（默认3306）

• 若监听端口不是3306，修改项目根目录.env文件中DB_PORT值为实际监听端口
• 若MySQL仅监听IPv6地址:::3306，临时可将DB_HOST改为::1测试，同时修改MySQL配置文件my.cnf中bind-address项为127.0.0.1，重启MySQL后生效
• 检查本地防火墙规则，确认回环接口访问3306端口未被拦截

3. 修复Unix套接字找不到问题 #

• 执行命令查询MySQL实际使用的套接字文件路径：

mysql --help | grep socket

常见默认路径为/var/run/mysqld/mysqld.sock或/tmp/mysql.sock

• 两种方式配置套接字路径二选一即可：
  • 方式1：在.env文件中新增配置项DB_SOCKET=上一步查询到的实际套接字路径，保持DB_HOST=localhost
  • 方式2：修改config/database.php中mysql连接配置段，补充unix_socket配置：

    'unix_socket' => env('DB_SOCKET', '查询到的实际套接字路径'),
    

• 若为Docker部署场景注意：PHP与MySQL分属不同容器时，不能使用localhost作为DB_HOST，必须填写MySQL容器的服务名或独立IP作为主机地址，同时确认两个容器在同一自定义网络下，端口映射配置正确。

4. 配置更新后必做操作 #

每次修改.env或数据库配置文件后，必须执行以下命令清除配置缓存，否则修改不会生效：

php artisan config:clear
php artisan cache:clear

缓存清除后先执行php artisan migrate验证数据库连接，连接正常后再测试用户注册接口。

内容的提问来源于stack exchange，提问作者Pedro Henrique Veloso