Laravel使用MySQL8.0执行php artisan migrate报2054错误的解决方法

云原生阿岚

2026-10-23

问题现象

我已在.env文件中按如下方式配置数据库：

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=test123
DB_USERNAME=root
DB_PASSWORD=16011996

运行php artisan migrate命令时出现如下报错：

Illuminate\Database\QueryException  : SQLSTATE[HY000] [2054] The server requested authentication method unknown to the client (SQL: select * from information_schema.tables where table_schema = test123 and table_name = migrations and table_type = 'BASE TABLE')

我已在MySQL中创建了名为test123的数据库schema，但仍出现该错误。尝试将DB_HOST改为127.0.0.1或localhost，均无效，该错误仅在使用MySQL 8.0版本时出现。我也已执行如下语句修改用户认证方式：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '16011996';
-- 执行返回：Query OK, 0 rows affected (0.01 sec)

语句执行成功，但仍然出现同样的错误。

修复方案

按以下顺序排查操作，即可定位并解决该类报错：

覆盖所有匹配的root用户条目，不要只修改单一条目
MySQL的用户认证是按「用户名+来源主机」的匹配规则生效的，你从程序发起TCP连接时，系统会优先匹配root@127.0.0.1、root@%这类条目，仅修改root@localhost的认证规则不会对TCP连接生效。直接执行以下语句修改所有root用户条目的认证方式，并刷新权限：
```
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '16011996';
ALTER USER 'root'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY '16011996';
ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY '16011996';
FLUSH PRIVILEGES;
```
清除Laravel的配置缓存
很多时候修改完.env文件后，Laravel实际读取的是之前生成的静态配置缓存，修改的配置根本没有生效。执行以下命令清空缓存，确保新配置被加载：
```
php artisan config:clear
php artisan cache:clear
```
强制走TCP连接，避免socket连接触发认证不兼容
当DB_HOST填写为localhost时，类Unix环境下的PDO MySQL扩展会自动切换为Unix socket连接，和TCP连接的认证链路完全独立。如果socket路径配置和MySQL实际运行路径不匹配，就会触发默认的caching_sha2_password认证握手。固定将DB_HOST设置为127.0.0.1，强制走TCP协议连接，不要使用localhost作为连接地址。
直连验证排除环境问题
不用Laravel框架，写一段最简PDO连接代码测试数据库连通性：
```
<?php
// 保存为test_conn.php直接在项目目录执行
$pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=test123', 'root', '16011996');
echo "数据库连接成功";
```
如果这段代码运行依然报2054错误，说明是MySQL用户认证配置没生效，回到第一步检查用户条目；如果代码运行能正常连通，说明是Laravel的配置读取异常，检查是否有系统环境变量覆盖了.env中的数据库配置。

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