.env 是 Laravel 启动时读取环境变量的唯一源头，修改前须确认 APPKEY 是否已生成；未生成则执行 php artisan key:generate，DB* 配置错误会导致连接失败，改完需清缓存并避免提交至 Git。
.env 文件不是“配置教程”，而是 Laravel 启动时读取环境变量的唯一源头——改错一个值，应用可能直接报 Class not found 或连不上数据库。
修改 .env 之前必须确认 APP_KEY 是否已生成
新项目首次运行 php artisan key:generate 才会写入 APP_KEY；如果手动创建了空 .env 却没执行这步，Laravel 会卡在加密组件初始化失败，报错信息是：Missing APP_KEY and no cipher is set。
- 执行前先检查
.env里是否有APP_KEY=base64:...这一行 - 没有就别急着改其他字段，先跑
php artisan key:generate（确保config/app.php中'cipher' => 'AES-256-CBC'没被注释或删掉） - 已有
APP_KEY但想重置？用php artisan key:generate --force，否则命令不生效
DB_* 配置项和实际数据库连接失败的对应关系
常见报错 SQLSTATE[HY000] [1045] Access denied for user，90% 是因为 .env 里这几个值没对上：
-
DB_HOST写成localhost而容器或远程 DB 实际走的是127.0.0.1（或反过来），MySQL 对这两个地址的用户权限可能是分开配的 -
DB_PORT默认是3306，但 Docker 环境常映射为3307或3308，漏改这里就会超时 -
DB_DATABASE名字带短横线（如my-app）？MySQL 允许，但 Laravel 的迁移命令会把它转成下划线路径，容易引发后续Migration table not found - 改完记得清缓存：
php artisan config:clear，否则旧配置还在内存里
部署时千万别把 .env 提交到 Git
本地开发可以放，但一旦进 Git，DB_PASSWORD、MAIL_PASSWORD、APP_KEY 就全暴露了——这不是“安全建议”，是硬性事实。
- 检查
.gitignore是否包含.env（Laravel 默认有，但有人手抖删了） - 如果已经误提交，光删文件不行，得用
git rm --cached .env再 commit，否则历史记录里还能挖出来 - 线上服务器不要靠上传
.env文件来配置，应通过环境变量注入（如 Nginx 的fastcgi_param或 systemd 的Environment=），Laravel 会优先读取系统级环境变量而非.env
最麻烦的不是写错某个值，而是改了之后忘了清缓存、忘了重启队列监听器、或者在多实例部署里只更新了一台机器的 .env。这些地方不会报错，但行为会不一致。
