Laravel项目启动失败的四大常见原因：一是APP_KEY未生成或格式错误，需用php artisan key:generate生成；二是pdo_mysql扩展未安装，需安装并重启PHP服务；三是路由未放在routes/目录下或未正确加载；四是APP_DEBUG=false导致错误不显示，本地开发必须设为true。
APP_KEY 为空或手动填了假值导致加密失败
新项目跑不起来、Session 读写异常、JWT 报 InvalidSignatureException，八成是 APP_KEY 没生成或被删了。Laravel 加密、Session、CSRF、signed URL 全依赖它，空值或非法格式（比如只写了 base64: 前缀没后面数据）会让整个安全链路崩掉。
- 用
php artisan key:generate生成，别手敲、别复制别人项目的值、别用str_random(32)这类过时函数 - 生成后检查
.env里是不是形如APP_KEY=base64:abcd...，长度约 44 字符；如果看到APP_KEY=SomeRandomString或空着，立刻重生成 - Docker 或 CI 环境容易漏掉这步——
php artisan key:generate必须在容器启动前执行，不能只写在 Dockerfile 的 COPY 后面
DB_CONNECTION=mysql 但没装 pdo_mysql 扩展
SQLSTATE[HY000] [2002] Connection refused 或更隐蔽的 Driver not supported，不是数据库地址错了，而是 PHP 根本没加载 MySQL 驱动。Laravel 默认用 mysql，但系统 PHP 可能只编译了 sqlite 或 pgsql。
- 运行
php -m | grep pdo看输出里有没有pdo_mysql；没有就装：Ubuntu 用sudo apt install php-mysql，Mac M1 用pecl install pdo_mysql - 改完扩展要重启 Web 服务（
php-fpm或 Apache），光 reload 不够，得sudo systemctl restart php*-fpm - 别信
phpinfo()页面里显示的“Loaded Modules”——它可能和 CLI 用的不是同一份配置，用php -i | grep 'pdo_mysql'更准
Route::get() 定义在 RouteServiceProvider 外面却找不到路由
写了 Route::get('/test', fn() => 'ok')，访问 404，控制台 php artisan route:list 也看不到。Laravel 6+ 路由默认只从 routes/web.php 和 routes/api.php 加载，直接写在其他文件（比如 app/Providers/AppServiceProvider.php）里不会自动注册。
- 路由定义必须放在
routes/目录下的文件中，或者显式在RouteServiceProvider::map()里调用Route::middleware('web')->group(base_path('routes/custom.php')) - 别在
config/app.php或bootstrap/app.php里写Route::get()—— 这些文件加载时机太早，Router 实例还没初始化 - 开发时想快速测试？用
routes/web.php最稳妥；生产环境要拆分路由，优先用Route::prefix()->group()而不是新建全局文件
APP_ENV=local 但 APP_DEBUG=false 导致错误不显示
页面白屏、API 返回空响应、日志里只有 production.ERROR，但 .env 明明写着 APP_ENV=local。关键点在于：Laravel 判断是否显示错误页面，只看 APP_DEBUG，和 APP_ENV 无关。设成 false，哪怕环境是 local，也会静默吞掉所有异常。
- 本地开发务必确保
APP_DEBUG=true；CI/测试环境可以关，但别在本地关 -
APP_ENV主要影响配置加载逻辑（比如config/logging.php里不同环境用不同 channel），不影响错误展示逻辑 - 改完
.env记得清缓存：php artisan config:clear，否则 Laravel 会读缓存里的旧值
最常被忽略的是缓存残留和扩展加载路径错配——改了 .env 不清缓存、装了扩展不重启 fpm、以为 APP_ENV=local 就等于能看到错误，这三个点卡住的人最多。
