在PHP 7.4+ MySQL环境下迁移Laravel 8时出现数据库访问被拒错误

对应触发场景：PHP7.4 运行环境、MySQL数据库驱动，执行迁移命令时抛出如下错误

Illuminate\Database\QueryException
SQLSTATE[HY000] [1045] 用户 'root'@'localhost' 访问被拒绝（已使用密码：是）
(SQL: 从 information_schema.tables 查询表，匹配条件为表所在schema为laravel、表名为migrations、表类型为BASE TABLE)

该错误本质是Laravel客户端提交的数据库身份凭证，没有通过MySQL服务端的权限校验，和迁移脚本的逻辑没有关联，按以下步骤排查即可解决：

• 核对项目根目录 .env 文件的数据库配置项，确保所有值和本地MySQL实际环境完全匹配：
  • DB_DATABASE：必须填本地MySQL中已实际创建的库名，没有提前创建laravel库的话，先手动在MySQL里执行建库语句再重试
  • DB_USERNAME：不要错用其他环境的账号，本地开发用root的话就填root，和实际登录MySQL的用户名保持一致
  • DB_PASSWORD：和本地MySQL对应用户的真实密码完全一致，注意：
    • 本地无密码的话，直接写DB_PASSWORD=，不要保留项目自带的占位值比如secret
    • 密码含特殊字符时不需要额外包裹引号，直接填实际值即可
• 清除旧的配置缓存：很多时候修改完.env文件没清缓存，Laravel还在读取之前缓存的错误数据库配置，执行以下命令后再重新跑迁移：
  • php artisan config:clear
  • php artisan cache:clear
• 修正连接主机和端口配置：
  • .env里的DB_HOST优先填127.0.0.1，不要混用localhost——部分MySQL配置下localhost会走unix socket连接，和TCP连接的权限规则不通用，很容易出现明明能登MySQL却连不上项目的问题
  • DB_PORT要和本地MySQL实际监听端口匹配，用集成环境（phpStudy、MAMP、宝塔面板）的用户要注意，部分环境会把默认3306端口改成其他值，要对应修改
• 校验MySQL侧的用户权限规则：
  • 用有权限的账号登录本地MySQL，执行SELECT user,host FROM mysql.user;，确认存在root@localhost对应的用户记录
  • 排查root账号的IP访问限制，确保本地命令行运行的PHP进程对应的来源IP，在MySQL用户的允许访问范围内

常见踩坑提醒

• PHP7.4版本下，.env的配置项不要加多余空格，比如DB_PASSWORD = 123456 里等号两侧的空格会被Laravel读到配置值中，导致实际提交的密码带了不可见的空格，校验失败
• 不要把.env文件另存为带BOM的UTF-8编码，文件头的BOM字符会被读到所有配置值的开头，连带数据库账号、密码都出现不可见乱码，直接触发权限拒绝

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