必须逐版本升级：8→9→10→11，不可跳步；需严格匹配php版本（11要求≥8.2）、同步更新laravel/*及配套包（如collision≥8.1、ignition≥2.4）、手动处理目录结构、配置废弃项与api变更，并完成缓存清理、路由验证及全量测试。
从 Laravel 8 升级到 LTS 版本（如 Laravel 10 或 11），不能跳步，必须严格走 8 → 9 → 10 → 11 的路径。Laravel 11 是当前最新 LTS 版本（支持至 2027 年），但它的底层结构、PHP 要求和生态依赖与 8.x 差距极大，中间缺失的兼容层无法绕过。
先确认环境与版本匹配
升级不是代码问题，首先是环境准入问题：
- 用
php -v查 PHP 版本：Laravel 9 要求 ≥ 8.0，Laravel 10 ≥ 8.1，Laravel 11 强制 ≥ 8.2 —— 若当前是 PHP 7.4 或 8.0，必须先升级 PHP 环境 - 运行
php artisan --version确认框架当前主版本；再查 官方 Upgrade Guide 对应版本的 Breaking Changes 清单 - 执行
composer outdated laravel/*和composer outdated spatie/* nunomaduro/* laravel/sanctum，识别哪些第三方包尚未适配目标版本
分阶段更新 composer.json 并约束依赖
每次只升一个主版本，且必须同步收紧所有关键约束：
- 从 8 → 9：把
"laravel/framework": "^8.0"改为"^9.0"，"php": "^8.0"；同时将"illuminate/*"全部对齐到"^9.0" - 从 9 → 10：改
"laravel/framework": "^10.0"和"php": "^8.1"；加--with-all-dependencies参数运行composer update laravel/framework，避免子依赖撕裂 - 从 10 → 11：改
"laravel/framework": "^11.0"和"php": "^8.2"；必须同时升级配套包，例如nunomaduro/collision≥ 8.1、spatie/laravel-ignition≥ 2.4、laravel/sanctum≥ 4.0
每轮升级后必做的三类手动检查
自动命令只能解决一半问题，剩下的是容易静默失效的关键点：
-
结构迁移：Laravel 11 默认移除
app/Http/Controllers目录，需运行php artisan upgrade（先composer require laravel-upgrade --dev），再手动调整路由中控制器引用方式（如改'HomeController@index'为[App\Http\Controllers\HomeController::class, 'index']） -
配置与缓存：升级后立即清空全部缓存：
php artisan config:clear && php artisan cache:clear && php artisan view:clear && php artisan route:clear；特别注意config/app.php中已废弃的 service provider（如PaginationServiceProvider）要删掉，否则启动报错 -
权限与日志等扩展包：若使用
spatie/laravel-permission，需比对新旧版database/migrations/是否有新增字段（如guard_name类型变更），并运行php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="config" --force合并配置
上线前验证清单（不可跳过）
不跑通这些，别上预发布环境：
- 能进
php artisan tinker，且可调用模型查询、队列 dispatch、缓存 get/set - 核心路由返回 HTTP 200，API 路由返回预期 JSON（注意 Laravel 10+
Route::apiResource()对 ID 类型更严格，/posts/abc会直接 404） - 数据库迁移可正向执行，且
php artisan migrate:rollback不报外键错误（DBAL change() 在 Laravel 10+ 易丢外键，建议改用 drop+change+foreign 三步法） - 所有 PHPUnit Feature 测试通过，尤其关注中间件顺序、表单验证响应、登录态保持逻辑
