Laravel升级需逐主版本进行，不可跳步；须确认当前版本、PHP兼容性、依赖包适配性，同步更新composer.json中框架及生态包版本，手动调整目录结构、配置文件、中间件与工厂语法，并执行缓存清理与测试验证。
Laravel 升级不是 composer update 一行命令就能搞定的事，必须按主版本逐级升级，跳步必崩。
怎么确认当前版本和目标版本是否可直升
直接运行 php artisan --version 看输出，比如显示 Laravel Framework 9.52.15，说明你用的是 9.x；再查官方文档确认 Laravel 11 已于 2025 年底正式 LTS（支持至 2027 年），但 9 → 11 不允许跨版升级——中间必须先升到 10.x，再升到 11.x。
- 查支持周期：Laravel 官网的
Supported Versions表格里，只有带 ✅ 的版本才是当前受支持的，过期版本（如 8.x）连安全补丁都不再提供 - 看 PHP 要求：Laravel 11 强制要求
php: "^8.2"，若你还在用 8.1，composer update会直接报错退出，别硬扛 - 第三方包卡壳很常见：比如
spatie/laravel-backupv8 支持 Laravel 10，但不兼容 11，得等它发 v9 或临时 fork 适配
升级时 composer.json 怎么改才不翻车
不能只改 "laravel/framework": "^11.0" 就完事。Laravel 主版本更新会带动一整套生态依赖升级，漏掉关键包会导致 Class not found 或 Target class does not exist。
- 必须同步更新配套包：比如
nunomaduro/collision得升到^8.1，spatie/laravel-ignition至少^2.4，laravel/sanctum对应升到^4.0 -
"php"版本约束要显式写进require，否则 Composer 可能忽略环境实际 PHP 版本，导致安装成功但运行时报ParseError - 加
--with-all-dependencies：执行composer update laravel/framework --with-all-dependencies，避免部分子依赖被锁在旧版引发冲突
升级后哪些文件必须手动检查
Composer 更新完只是第一步，Laravel 11 彻底重构了项目骨架：默认删掉了 app/Http/Controllers、app/Http/Middleware、app/Providers 这些目录，AppServiceProvider 的 register() 和 boot() 逻辑也需重审。
-
config/app.php中废弃的'providers'数组项（如Illuminate\Pagination\PaginationServiceProvider::class）要删掉，否则启动报错 -
app/Kernel.php里$middlewareGroups结构已简化，Laravel 11 移除了web组中默认的EncryptCookies等中间件，如果你的路由依赖它们，得手动加回去 -
database/factories下的模型工厂语法从类定义变为闭包，旧写法class UserFactory extends Factory会直接报Class "UserFactory" not found
测试和缓存清理最容易被跳过的环节
很多人跑完 composer update 就访问首页，发现白屏或 500，却没意识到是缓存没清干净，或者测试根本没跑。
- 必须依次执行：
php artisan config:clear、php artisan cache:clear、composer dump-autoload，缺一不可 -
php artisan test不是可选动作：Laravel 11 修改了assertDatabaseHas()的底层行为，某些断言可能“看似通过实则漏判”，建议至少跑一遍核心业务测试用例 - 别信本地“能打开首页”：Laravel 11 默认禁用
APP_DEBUG=true时的详细错误页，生产环境配置下错误会被静默吞掉，务必开日志查storage/logs/laravel.log
最常被忽略的是中间件注册方式变更和工厂语法迁移，这两处不手动改，项目根本起不来；而最大的陷阱是以为升级完就万事大吉，结果上线后队列任务 silently fail 或邮件发送丢失，因为 Mail::to()->send() 在 11.x 中对 to() 参数校验更严了。
