直接运行 composer create-project 启动 Laravel 11 项目是可行的，但跳过初始化 checklist 会导致后续部署卡在缓存、密钥、目录权限或环境变量上——这些问题在本地开发时几乎不暴露，一上生产就 500。

确认 PHP 8.2+ 与 Composer 版本兼容

Laravel 11 强制要求 PHP ≥ 8.2，且依赖 Composer 2.5+ 的自动加载优化。低于此版本会触发 Class "Illuminate\Foundation\Application" not found 或 Target PHP version mismatch 错误。

执行 php -v 确保输出含 8.2. 或更高小版本（如 8.2.24）

执行 composer --version 验证是否 ≥ 2.5.0；若为 2.4.x，需升级：composer self-update

PHP 必须启用 mbstring、openssl、pdo、tokenizer 和 xml 扩展，缺一则 artisan 命令无法启动

初始化后必须立即执行的三步验证

创建项目后不要急着写路由或改配置，先跑通基础链路。Laravel 11 的流式结构移除了部分兜底逻辑，出错反馈更“硬”。

进入项目目录后，立刻运行 php artisan key:generate —— 即使 .env 已存在，也必须重生成 APP_KEY，否则 Session、加密 Cookie 全失效

执行 php artisan config:clear && php artisan cache:clear，清空所有旧缓存（尤其当你从旧项目复制了 bootstrap/cache/ 目录）

手动检查 storage/ 和 bootstrap/cache/ 是否可写：ls -ld storage bootstrap/cache，权限应为 drwxr-xr-x 或更宽松；若为 drw-------，需 chmod -R 755 storage bootstrap/cache

env 文件与 APP_ENV 的强绑定陷阱

Laravel 11 默认关闭 env() 函数在缓存配置中的使用，一旦 APP_ENV 不是 local 或 testing，config:cache 就会拒绝运行，并报错 Environment detection failed。

.env 中必须显式定义 APP_ENV=local（开发）或 APP_ENV=production（预发/生产），不能留空或注释掉

APP_DEBUG 必须与 APP_ENV 匹配：开发环境设为 true，生产环境必须为 false，否则 php artisan config:cache 会静默失败

检查 config/app.php 中是否残留 env('APP_NAME') 类调用 —— Laravel 11 推荐全部替换为 config('app.name')，否则缓存后读不到值

首次启动前的 route:cache 安全检查

Laravel 11 的 route:cache 更严格，不再容忍闭包路由、动态域名或未注册的控制器类名。未检查就运行会导致整个应用不可访问。

打开 routes/web.php 和 routes/api.php，确认所有路由都使用数组语法或控制器方法引用，例如 Route::get('/home', [HomeController::class, 'index'])，而非 Route::get('/home', function () { ... })

检查控制器类路径是否真实存在，且命名空间与文件位置一致（Laravel 11 默认移除了 app/Http/Controllers 的自动 namespace 声明，需手动补全）

若项目含多域名路由（Route::domain(...)），确保已通过 php artisan route:list 验证无 Domain not defined 报错

最易被忽略的是 storage/logs/laravel.log 的写入权限和 APP_KEY 的唯一性——这两个点不出错时一切正常，一旦出错，日志为空、Session 无效、加密数据全乱，排查成本远高于初始化时多敲两行命令。

Tags: Laravel 11 项目初始化 checklist

分享到：