Laravel 10 数据库连接报错本质是 PDO 建立 TCP 连接时被系统或 MySQL 拒绝，非框架问题；主因四类：DB_HOST 与网络环境不匹配（如 Docker 必须用容器名而非 localhost）、MySQL 服务未启动或端口未暴露、用户权限或 caching_sha2_password 认证插件不兼容、.env 配置未生效（含特殊字符未单引号包裹、未清缓存）。
Laravel 10 数据库连接报错，本质不是框架出问题，而是 PDO 尝试建立 TCP 连接时被操作系统或 MySQL 服务直接拒绝了。错误发生在 Laravel 加载配置之后、执行 SQL 之前，所以查模型、改迁移、清缓存都压根没用——路都没通，还谈什么走车。
下面分四类真实原因讲清楚，每类都带可操作的验证和解法：
DB_HOST 和网络环境不匹配
Docker、Homestead、本地 MAMP/XAMPP 各自对 localhost 的解析逻辑完全不同：
- 在 Docker 容器里写
DB_HOST=localhost→ PHP 会去连容器自己的 127.0.0.1（没 MySQL） - 在 Mac 上用 MAMP，MySQL 默认端口是
8889，但.env还写着DB_PORT=3306→ 连不上 - Linux 或某些 Docker 网络中，
localhost会尝试走 Unix socket，而DB_SOCKET没配 → 报No such file or directory
✅ 做法：
- 本地开发优先用
DB_HOST=127.0.0.1 - Docker 场景必须写数据库容器名（如
mysql、db），不能写localhost或127.0.0.1 - MAMP/XAMPP 用户用终端执行
mysql -h 127.0.0.1 -P 8889 -u root -p测试是否通
MySQL 服务根本没起来，或端口没暴露
Connection refused 不是密码错，是“敲门没人应”。常见情况：
- macOS 上 MySQL 没通过
brew services start mysql启动 - Docker 容器没运行，或
docker run漏了-p 3306:3306 - 云服务器防火墙拦住了
3306端口，或安全组没放行
✅ 快速验证：
- 终端运行
sudo netstat -tuln | grep :3306，看有没有LISTEN -
docker ps确认数据库容器在运行且端口映射正确 - 用
mysql -h $DB_HOST -P $DB_PORT -u $DB_USERNAME -p手动连一次（别依赖 Laravel）
用户权限和认证插件不兼容
MySQL 8 默认用 caching_sha2_password 插件，而 PHP 7.3 及更早版本的 mysqlnd 扩展不支持 → 表现为卡住、超时、或报 SQLSTATE[HY000] [2054]。
另外，权限只开了 'user'@'localhost'，但 Laravel 是从 '127.0.0.1' 连的 → 权限不匹配，报 Access denied。
✅ 解法：
- 登录 MySQL 执行：
ALTER USER 'your_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password'; FLUSH PRIVILEGES;
- 或升级 PHP 到 7.4+，并确认
php -i | grep mysqlnd输出含caching_sha2_password - 授权时明确加 host：
GRANT ALL ON db.* TO 'user'@'127.0.0.1' IDENTIFIED BY 'pass';
.env 配置看似改了，其实没生效
.env 有高优先级，但改完不清理缓存、格式写错、特殊字符没包裹，都会让配置“静默失效”：
-
DB_PASSWORD=p@ss/w?rd→?被当 URL 参数截断，实际传的是p@ss/w -
DB_PASSWORD="p@ss/w?rd"→ 双引号在某些 shell 下会被展开变量 -
.env改了但没运行php artisan config:clear→ 还在用旧缓存
✅ 正确做法：
- 密码含
@ / : ? # $等字符，一律用单引号包裹：DB_PASSWORD='p@ss/w?rd' - 改完立即执行：
php artisan config:clear php artisan optimize:clear # 防 OPCache 缓存旧值
- 进
php artisan tinker，输入：env('DB_HOST') config('database.connections.mysql.host')两个输出必须一致，否则说明没生效
不复杂但容易忽略
