Laravel连接MySQL数据库方法

本文详细讲解了 Laravel 项目连接 MySQL 数据库的完整实践指南，涵盖核心配置要点（.env 文件中 DB_CONNECTION、DB_HOST、DB_PORT、DB_DATABASE 四项必改设置及密码含特殊字符时的单引号包裹技巧）、常见连接失败场景的精准诊断方法（通过 DB::connection()->getPdo() 快速验证，并结合三类典型 SQLSTATE 错误码定位权限、网络或数据库不存在问题）、MySQL 8 兼容性关键对策（必须切换为 mysql_native_password 认证插件），以及极易被忽视却至关重要的配置缓存清理步骤（config:clear 或手动删除 bootstrap/cache/config.php），帮助开发者避开绝大多数本地与 Docker 环境下的数据库连接坑，真正实现开箱即连、错误可控、调试高效。

数据库配置文件在哪、改哪些键

Laravel 的数据库配置集中在 .env 文件里，不是 config/database.php —— 后者只是读取环境变量的中间层。直接改 .env 才生效。

关键配置项有四个，缺一不可：

• DB_CONNECTION=mysql（必须是 mysql，不是 mysqli 或 pdo_mysql）
• DB_HOST=127.0.0.1（别用 localhost，MySQL 会走 socket，可能连不上）
• DB_PORT=3306（Docker 或远程库常改端口，不写默认 3306，但显式写更稳）
• DB_DATABASE=your_db_name（库名必须已存在，Laravel 不自动建库）

密码含特殊字符（如 @、/）时，整个 DB_PASSWORD=xxx 值要用单引号包住，否则 dotenv 解析失败。

连接失败时先看什么错误信息

运行 php artisan tinker 后执行 DB::connection()->getPdo(); 是最快验证方式。失败时常见三类报错：

• SQLSTATE[HY000] [1045] Access denied for user → 用户名/密码错，或 MySQL 没授权该用户从当前 host 连接
• SQLSTATE[HY000] [2002] Connection refused → DB_HOST 或 DB_PORT 不通，可能是 MySQL 没启动、防火墙拦截、Docker 网络未连通
• SQLSTATE[HY000] [1049] Unknown database → DB_DATABASE 值不存在，得手动在 MySQL 里 CREATE DATABASE

注意：Laravel 默认不显示完整 PDO 错误，加 DB_DEBUG=true 到 .env 才能看到底层报错细节。

本地开发用 MySQL 8 要关掉密码插件

MySQL 8 默认用 caching_sha2_password 插件，但 Laravel 8 及更早版本的 PDO MySQL 驱动不支持，会卡在认证阶段。

解决方法只有两个，任选其一：

• 重置用户密码并指定旧插件：ALTER USER 'your_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_pass';
• 新建用户时就指定：CREATE USER 'new_user'@'%' IDENTIFIED WITH mysql_native_password BY 'pass';

别试图升级 PDO 或换驱动——PHP 自带的 mysqlnd 在 PHP 7.4–8.2 仍不原生支持 caching_sha2_password，硬刚只会浪费时间。

查数据前记得清缓存

改完 .env 后，Laravel 会把数据库配置缓存进 bootstrap/cache/config.php。如果之前跑过 php artisan config:cache，新配置根本不会加载。

开发阶段最稳妥的做法：

• 删掉缓存文件：rm bootstrap/cache/config.php
• 或者临时禁用缓存：php artisan config:clear（这个命令只清内存缓存，不删文件）

顺带一提：php artisan migrate 也会读缓存配置，所以迁移失败前，先确认配置没被缓存锁死。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Laravel连接MySQL数据库方法》文章吧，也可关注golang学习网公众号了解相关技术文章。