php artisan laravel:upgrade命令可自动处理大量高危变更，但需在Laravel 8.x+运行，安装laravel/upgrade --dev后执行，配合备份、版本选择、文件校验（如移除file缓存驱动、更新中间件引用）及缓存清理与路由验证方可生效。
想把旧版 Laravel 项目快速升级到新主版本，又怕手动改配置、删废弃类、补返回类型出错？php artisan laravel:upgrade 命令能自动处理大量高危变更，但必须配合正确前置条件和后续验证才能真正生效。
安装升级助手并初始化
进入项目根目录，执行：
composer require laravel/upgrade --dev
这一步必须在 【Laravel 8.x 或更高版本】 下运行，低于 8.x 的项目（如 7.x）无法加载该命令——它依赖 Symfony Console 5+ 和 Illuminate\Support\ServiceProvider 的新版契约。
安装完成后，运行：
php artisan list | grep "laravel:upgrade"
立即学习“PHP免费学习笔记（深入）”；
若看到命令列表中出现 laravel:upgrade，说明已就绪。
执行自动升级流程
第一步：备份当前代码与数据库快照，尤其要保留未提交的 .env 和 config/ 下自定义配置文件。
第二步：运行升级命令：
php artisan laravel:upgrade
第三步：按提示选择目标版本（如 9.x → 10.x），工具会自动检测当前版本并列出拟修改文件清单。它将重写 bootstrap/app.php 结构、替换 app/Providers/RouteServiceProvider.php、移除已弃用的 Facade 引用（如 Illuminate\Support\Facades\Hash）、更新 composer.json 中的 laravel/framework 版本约束。
第四步：确认无误后输入 y 回车，工具开始批量写入变更。此时不要中断终端进程，否则可能留下半成品文件导致路由无法加载。
关键手动校验项
升级完成后，立刻检查 config/cache.php 是否还存在 'stores' => ['file' => [...]] 配置块——【Laravel 10+ 已彻底移除 file 缓存驱动】，残留会导致 cache:clear 失败并抛出 InvalidArgumentException。
打开 app/Http/Kernel.php，确认 $middlewareGroups['web'] 中是否仍引用了已被移除的 \Illuminate\Session\Middleware\StartSession::class —— Laravel 10 默认改用 \Illuminate\Cookie\Middleware\EncryptCookies::class + session middleware 分离机制，硬编码旧中间件会引发 Request 对象构造失败。
运行 php artisan config:clear → php artisan config:cache，强制刷新缓存；再执行 php artisan route:list，验证所有路由是否正常注册。若出现 Class 'Illuminate\Support\Facades\Hash' not found 错误，说明某处仍残留旧 Facade 引用，需全局搜索并替换为 Illuminate\Hashing\HashManager。
