Laravel升级必须逐主版本进行，不可跨大版本直连；需确认PHP版本兼容性、同步更新第三方包、使用官方升级助手执行结构迁移，并手动处理废弃API与辅助函数。
你需要把Laravel项目从旧版升级到新版，但又担心改完composer.json就直接报错、服务起不来、路由404或者中间件失效——这不是操作不熟练，是没踩对升级节奏和关键检查点。
确认当前版本与目标版本是否可直达
运行php artisan --version，看输出类似Laravel Framework 9.52.15，说明你卡在9.x；查Laravel官网Supported Versions表格，发现9→11被明确标记为【不允许跨版】，必须先升10.x再升11.x。
若php -v显示8.1.10，而目标是Laravel 11，则【PHP必须先升到8.2+】，否则composer update会静默失败，连错误提示都不给全。
用composer outdated "laravel/*"扫一遍生态包，比如看到laravel/sanctum v3.2.1，而Laravel 11要求^4.0，就得提前记下这个要手动改。
修改composer.json的三处硬性改动
方法一：只改framework版本号 → 最常见翻车点。把"laravel/framework": "^9.0"改成"^10.0"后，artisan可能直接报Class not found: Illuminate\Support\Facades\Facade——因为illuminate/support没同步升，依赖树断了。
方法二：同步更新强关联包。除了framework，必须一起改："nunomaduro/collision": "^7.0"（对应Laravel 10）、"spatie/laravel-ignition": "^2.0"、"laravel/sanctum": "^3.2"，漏一个就可能启动失败。
方法三：显式声明PHP版本约束。在require块里加一行"php": "^8.1"（Laravel 10）或"^8.2"（Laravel 11），否则Composer可能沿用旧环境约束，装出降级依赖。
执行升级命令与结构迁移
第一步：安装升级助手
运行composer require laravel/upgrade --dev，它不是可选插件，是Laravel 10+官方指定的结构迁移工具。
第二步：触发自动重构
执行php artisan upgrade，它会重写app/Providers/HttpKernel.php、清理废弃的$middlewareGroups键、补全缺失目录（如Laravel 11默认删掉app/Http/Controllers，这一步会重建）。
第三步：处理缓存残留php artisan config:clear && php artisan route:clear && php artisan view:clear——不能只清config，Laravel 10+的config/logging.php结构已重写，旧缓存会导致日志驱动崩溃甚至整个应用白屏。
检查三类易崩代码
路由控制器引用必须显式写出完整类名。Laravel 10起默认关闭自动命名空间绑定，Route::get('/', 'HomeController@index')这种字符串写法仍能跑但已废弃，且Laravel 11彻底移除支持，必须全换成[App\Http\Controllers\HomeController::class, 'index']。
DBAL外键突然消失？不是Laravel删的，是Doctrine DBAL v3.5+在change()字段时默认重建表结构，不保留外键。遇到$table->string('email', 191)->change()，得拆成三步：dropForeign() → change() → foreign()，且字段类型必须严格一致（如unsignedBigInteger不能写成bigInteger）。
搜索项目中所有str()、array_*()辅助函数调用，全部替换成Str::或Arr::命名空间调用——Laravel 11已移除全局辅助函数，不改就报Call to undefined function。
