.
QQ扫一扫联系
从 Laravel 9 升级到 Laravel 12 是一个涉及多个版本迭代的过程,以下是分阶段的规则变动总结及升级注意事项:
PHP 版本要求提升
最低支持 PHP 8.1(Laravel 9 支持 PHP 8.0)。
影响:需确保服务器环境兼容,检查代码中是否使用已废弃的 PHP 8.0 特性。
功能标志管理(Laravel Pennant)
新增官方功能标志包,支持渐进式功能发布和 A/B 测试。
适配建议:若使用自定义功能标志逻辑,可迁移至 Pennant 以简化实现。
验证规则默认可调用
通过 Artisan 生成的验证规则默认支持 __invoke()
方法。
代码调整:旧版需显式实现 passes()
和 message()
方法的规则需更新。
弃用功能移除
移除 Route::home
、edispatchNow
等方法。
替代方案:使用 url('/')
替代路由首页,队列分发改用 dispatch_now()
。
类型声明增强
框架代码全面添加原生类型提示(如 public function handle(Request $request): Response
)。
影响:自定义代码需遵循严格类型检查,避免类型不匹配错误。
目录结构重构
移除目录:app/Exceptions
、app/Http/Middleware
。
配置集中化:配置整合到 .env
文件,可通过 php artisan config:publish
生成独立配置文件。
路由精简:默认路由文件从 4 个(web.php
, api.php
, console.php
, channels.php
)精简为 2 个(需手动生成 API 路由)。
核心组件调整
Http/Kernel 移除:请求生命周期由 Bootstrap/App
类管理,需调整依赖旧内核的中间件注册逻辑。
模型 Casts 方法化:属性定义从 $casts
数组改为 casts()
方法。
// Laravel 9 写法 protected $casts = ['is_admin' => 'boolean']; // Laravel 11 写法 public function casts(): array { return ['is_admin' => 'boolean']; }
PHP 版本要求提升至 8.2
兼容性检查:确保依赖包支持 PHP 8.2,使用 composer outdated
检测过时依赖。
安全与性能优化
配置级联功能:支持删除未使用的配置项,简化调试。
Dumpable Trait:统一调试方法,替代原有 dd()
和 dump()
。
维护性版本,变动较小
聚焦上游依赖更新(如 Symfony 6.2+),无重大破坏性变更。
PHP 版本支持:维持 PHP 8.2-8.4,建议升级至 PHP 8.4 以利用最新优化。
新入门套件引入
提供 React/Vue/Livewire 模板,集成 Shadcn UI 组件和 WorkOS AuthKit。
适配建议:新建项目可直接使用模板,现有项目无需强制迁移。
依赖管理优化
更新 Laravel Installer 至最新版:composer global require laravel/installer
。
备份与测试
升级前备份代码、数据库及配置文件。
使用 php artisan test
运行单元测试,手动验证关键功能(如认证、队列、邮件)。
依赖冲突解决
运行 composer update
后若出现依赖冲突,通过 composer why
分析原因,选择性更新或替换包。
自动化工具辅助
使用 Laravel Shift 自动处理大部分代码适配(如路由、模型调整)。
官方升级命令:php artisan laravel-new:upgrade
(Laravel 11+ 支持)。
长期支持策略
Laravel 12 提供 18 个月 Bug 修复和 2 年安全更新,建议生产环境优先升级。
路由文件缺失
现象:升级后 API 路由失效。
解决:运行 php artisan install:api
生成 routes/api.php
。
中间件失效
原因:Laravel 11 移除了 app/Http/Middleware
目录。
修复:将自定义中间件移至 app/Middleware
,并在 Kernel.php
中注册。
配置加载错误
现象:环境变量未生效。
解决:检查 .env
文件格式,运行 php artisan config:clear
清除缓存。
通过以上分阶段适配和工具辅助,可最大限度减少升级风险。建议参考官方升级指南(Laravel 9→10、Laravel 10→11、Laravel 11→12)逐步操作。
.