Laravel 修改 .env 后需执行 php artisan config:clear 清缓存，且 DB_HOST 应用 127.0.0.1 而非 localhost；特殊字符密码须 URL 编码，DB_URL 更可靠；调试时确保 APP_DEBUG=true 并查日志。
数据库配置文件里 .env 的值没生效？
Laravel 启动时不会自动重读 .env，改完配置后必须清缓存。常见现象是改了 DB_HOST 或 DB_PASSWORD，但 php artisan tinker 里 config('database.connections.mysql.host') 还是旧值。
- 执行
php artisan config:clear（不是cache:clear） - 如果用了 OPCache，还得加
php artisan optimize:clear - 确认
.env文件权限正常（非 root 写入、无 BOM 头），Windows 下用记事本保存易出 BOM - 检查
APP_ENV是不是误设为production，导致 Laravel 默认不加载.env
mysql 扩展已启用但连接仍报 SQLSTATE[HY000] [2002]
这个错误本质是 PHP 连不上 MySQL 服务，和 Laravel 关系不大，但容易误以为是框架问题。
- 先在命令行试：
mysql -h 127.0.0.1 -P 3306 -u homestead -p（注意用127.0.0.1而非localhost，后者可能走 socket 导致行为不一致） - 检查
DB_HOST值：Docker 环境下不能写localhost，得用宿主机 IP 或 Docker 网络别名（如mysql） - 确认 MySQL 容器或服务确实在运行：
docker ps | grep mysql或systemctl status mysql -
DB_PORT默认是3306，但 MAMP/XAMPP 可能改过，务必核对
DB_USERNAME 和 DB_PASSWORD 包含特殊字符时连不上
Laravel 用 PDO 构建 DSN，:、@、/、? 这些字符会破坏 URL 格式，导致解析失败，错误信息常是 SQLSTATE[HY000] [1045] 且用户名显示异常。
- 把密码里的
@换成%40，:换成%3A，/换成%2F（URL 编码） - 更稳妥的做法：改用
DB_URL配置项，直接写完整 DSN：DB_URL=mysql://user:%40pass%3Aword@127.0.0.1:3306/dbname - 不要在
.env里用单引号或双引号包裹密码——Laravel 的 Dotenv 不支持引号转义
API 请求返回 500 却没报数据库错误？
默认情况下，Laravel API 的异常响应被 App\Exceptions\Handler 拦截，敏感的数据库连接细节（比如真实 host 或用户）会被隐藏，只留 “Internal Server Error”，查不到根因。
- 临时打开调试：确保
APP_DEBUG=true且APP_ENV=local - 看日志而不是浏览器响应：
tail -f storage/logs/laravel.log，搜索PDOException或Connection refused - 在
config/database.php的 mysql 配置里加'options' => [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]，强制抛出异常 - API 路由别漏掉
->middleware('api')，否则可能走 web 中间件栈，触发 session 启动失败掩盖真实 DB 问题
最常被跳过的其实是 config:clear 和 127.0.0.1 vs localhost 的区别——这两个点卡住的人最多，而且查日志也看不到明显线索。
