Laravel主版本升级本质是切换底层契约，需分四步操作：①比对官方Breaking Changes确认断层点；②用laravel/upgrade扫描兼容性；③分阶段更新框架、清缓存、修正index.php和EventServiceProvider；④验证HTTP内核继承与队列multi-modal配置。
当你在 Laravel 项目中执行 composer update laravel/framework 却发现路由不生效、中间件报错、队列任务卡死，甚至 php artisan serve 直接抛出 Class not found，这不是 Composer 的锅——而是你跳过了主版本升级中那些被框架刻意隐藏、却决定成败的底层契约变更。
理解 Laravel 主版本升级的本质
主版本升级（如 v10 → v11 或 v11 → v12）不是“更新依赖”，而是切换一套全新的内核契约：服务容器绑定方式重写、HTTP 内核中间件管道重构、Eloquent 模型属性访问逻辑变更、Blade 编译器 AST 解析规则迭代。这些变更不体现在 composer.json 的版本号里，而藏在 vendor/laravel/framework/src/Illuminate 下数百个类的构造函数签名、方法返回类型、静态属性生命周期中。
跳过契约校验直接升级，等于用旧钥匙开新锁——钥匙能插进去，但拧不动。
第一步：确认当前版本与目标版本的契约断层点
打开项目根目录下的 composer.json，定位 "laravel/framework" 行，记录当前约束（例如 "^10.48.0"）→ 进入 Laravel 官方升级指南，找到对应版本的「Breaking Changes」章节。
【必须逐行比对】 重点关注以下四类契约变更：
① app/Providers/AppServiceProvider.php 中 register() 方法内调用的 $this->app->bind() 是否仍接受字符串键名（v12 已废弃字符串绑定，强制使用类名或接口）；
② app/Http/Kernel.php 中 $middleware 数组是否混用了闭包与类名（v12 要求全部为类名或已注册的中间件别名）；
③ 所有 Eloquent 模型中是否存在手动覆写的 getDateFormat() 方法（v12 移除了该方法，改由 $casts 控制时间格式）；
④ Blade 模板中是否使用了 @pushonce 指令（v12 已删除，需替换为 @push + 手动去重逻辑）。
第二步：用升级助手触发契约兼容性扫描
运行 composer require laravel/upgrade --dev → 执行 php artisan upgrade:check。
该命令会启动一个轻量级解析器，遍历 app/ 和 config/ 目录下所有 PHP 文件，比对当前代码与目标版本的 AST 结构差异。它不修改任何文件，只输出三类结果：
• ✅ Safe：无契约冲突（如普通控制器方法）；
• ⚠️ Review：需人工判断（如自定义中间件的 handle() 方法签名是否匹配 v12 的 Request $request, Closure $next 强类型要求）；
• ❌ Breaking：必须修改（如 DB::raw() 在 v12 中返回对象而非字符串，所有 strpos(DB::raw(...), 'xxx') 将直接报错）。
注意：扫描结果中的文件路径是相对路径，但行号精确到字符位置——这是你修复时的唯一坐标系。
第三步：分阶段替换核心契约载体
不要一次性运行 composer update。按以下顺序执行：
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
① 先执行 composer update laravel/framework "12.*"（指定精确主版本），此时 vendor/ 中仅更新框架代码，composer.lock 记录新哈希值；
② 立即运行 php artisan clear-compiled && php artisan config:clear && php artisan view:clear，清除所有缓存——v12 的服务容器编译器不再兼容 v11 的 bootstrap/cache/compiled.php，残留文件会导致 Class not found 错误；
③ 修改 public/index.php 第 14 行：
原内容：$app = require_once __DIR__.'/../bootstrap/app.php';
改为：
$app = require_once __DIR__.'/../bootstrap/app.php';<br>if (class_exists('Illuminate\Foundation\Application')) {<br> Illuminate\Foundation\Application::setInstance($app);<br>}
—— 这是 v12 新增的实例绑定强制校验，缺失将导致服务容器无法解析任何门面。
④ 运行 php artisan upgrade:apply，该命令会自动重写 app/Providers/EventServiceProvider.php 中的 $listen 数组语法（v12 要求事件类必须带完整命名空间，不再支持短名自动补全）。
第四步：验证 HTTP 内核与队列驱动的契约同步
方法一：检查 HTTP 请求生命周期是否断裂
启动开发服务器：php artisan serve → 访问任意路由 → 查看终端日志。若出现 Call to undefined method Illuminate\Foundation\Http\Kernel::sendRequestThroughRouter()，说明 app/Http/Kernel.php 未继承 v12 的 Illuminate\Foundation\Http\Kernel 抽象类（v12 中该方法已移至父类，子类必须显式声明 use Illuminate\Foundation\Http\Kernel as HttpKernel; 并继承 HttpKernel）。
方法二：验证多模态队列是否激活
v12 默认启用 multi-modal 队列驱动，但仅当 config/queue.php 中存在 'multi_modal' 配置项时才加载。若你的项目仍使用 'redis' 作为默认驱动，需手动在 config/queue.php 的 'default' 键后添加：'default' => env('QUEUE_CONNECTION', 'redis'),'connections' => [...],'multi_modal' => [ // 此块必须存在，即使暂不使用 ] —— 否则 php artisan queue:work 会因找不到驱动类而终止。
【关键前提】 v12 的队列监听器 now 必须实现 Illuminate\Contracts\Queue\ShouldQueue 接口，且构造函数参数不得含未绑定到服务容器的原始类型（如 int $id），否则 make() 解析失败。
