WSL环境下Laravel用Sail启动报SQLSTATE[HY000] [2002]数据库连接错误

问题根因 #

你运行php artisan serve时，Laravel服务直接跑在WSL的Ubuntu系统本地，localhost/127.0.0.1指向的是WSL系统本身，自然能正常连接你安装在WSL/Windows本地的MySQL。
但用Sail启动时，Laravel应用是运行在Docker内部的独立PHP容器中，此时容器内的localhost/127.0.0.1指向的是PHP容器本身，这个容器里没有部署MySQL服务，所以会抛出连接错误。

你之前尝试的unix_socket配置仅适用于服务和MySQL跑在同一操作系统下用套接字连接的场景，Docker容器和宿主机文件系统隔离，无法直接读取宿主机的socket文件，所以该方案无效。

解决方案 #

根据你是否使用Sail自带的MySQL服务，分为两种处理方式：

方案1：使用Sail自带的MySQL容器（Sail标准用法，推荐） #

Sail默认会自动创建独立的MySQL容器，无需你本地安装MySQL：

1. 确认项目根目录下的docker-compose.yml文件中存在mysql服务配置，默认Sail生成的配置中mysql服务的名称就是mysql
2. 修改.env文件的数据库配置如下：

DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=thc
DB_USERNAME=sail
DB_PASSWORD=password

默认Sail MySQL容器的普通用户名为sail，密码为password，root用户密码同样为password，可自行修改docker-compose.yml中的环境变量自定义
3. 重启Sail生效：

./vendor/bin/sail down
./vendor/bin/sail up -d

4. 执行迁移初始化Sail MySQL容器中的库表：

./vendor/bin/sail artisan migrate

方案2：连接安装在WSL/Windows本地的MySQL #

如果你要保留本地MySQL中的已有数据，可按以下配置调整：

1. 先给本地MySQL开启远程访问权限，登录本地MySQL执行以下SQL：

GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' IDENTIFIED BY '你的本地MySQL root密码';
FLUSH PRIVILEGES;

同时修改本地MySQL的配置文件，将bind-address参数改为0.0.0.0，重启MySQL服务生效。
2. 修改.env中的DB_HOST为Docker容器访问宿主机的固定域名：

DB_HOST=host.docker.internal
DB_PORT=3306
DB_DATABASE=thc
DB_USERNAME=root
DB_PASSWORD=你的本地MySQL root密码

3. 重启Sail即可正常连接。

快速排查技巧 #

如果修改后仍然报错，可进入Sail的PHP容器中手动测试连通性定位问题：

1. 执行./vendor/bin/sail exec laravel.test bash进入PHP容器
2. 用ping命令测试网络连通：
   • 用方案1的话执行ping mysql，看是否能解析到IP
   • 用方案2的话执行ping host.docker.internal，看是否能连通宿主机
3. 用mysql命令行手动测试连接，确认账号密码、库名是否正确。

内容的提问来源于stack exchange，提问作者Rreit