升级 Laravel 需严守 PHP/Composer 版本、逐级迁移、同步更新配套包、手动检查路由/外键/工厂/配置变更，并执行缓存清理、全量测试及核心链路验证。
升级 Laravel 新版本不是改个版本号就能跑起来的事，关键在“稳”和“准”。当前（2026年9月）主流生产环境多处于 Laravel 10 或正向 11/12 迁移，而 Laravel 10 已于 2025 年 2 月停止安全支持，继续使用存在明确风险。下面从实操角度梳理真正要盯住的几件事。
必须满足的硬性门槛
跳过这一步，composer update 会直接失败：
- PHP 版本严格匹配：Laravel 10 要求 ≥8.1；Laravel 11 要求 ≥8.2；Laravel 12 要求 ≥8.2（最高支持 8.4）
- Composer 版本 ≥2.2.0（Laravel 10+），建议用最新稳定版
- 确认当前框架版本：运行 php artisan --version，确保是可直达目标版本的前一主版本（如升 10 必须已是 9.x，不能从 8.x 直升）
- 检查第三方包兼容性：重点关注 laravel/sanctum、spatie/laravel-ignition、doctrine/dbal 等，它们往往有对应主版本约束
composer.json 修改要点
只改 "laravel/framework": "^X.0" 是最常见翻车点：
- 同步更新配套包：例如升到 Laravel 11，需配 "nunomaduro/collision": "^8.1"、"laravel/sanctum": "^4.0"、"phpunit/phpunit": "^11.0"
- 显式声明 PHP 版本约束："php": "^8.2" 写进 require，避免 Composer 忽略环境实际版本
- 删掉 "minimum-stability": "dev" 类非稳定设置，防止拉入 alpha/beta 包
- 执行命令时加 --with-all-dependencies：如 composer update laravel/framework --with-all-dependencies，防止子依赖版本撕裂
代码与结构必须手动检查项
官方升级助手（php artisan laravel:upgrade）能处理一部分，但这些仍需人工核对：
- 路由写法变更：Laravel 10+ 废弃字符串式控制器引用（如 'HomeController@index'），统一改为数组语法 [HomeController::class, 'index']，且需提前 use
- 外键丢失问题：升级后执行 php artisan migrate 若发现外键消失，大概率是 doctrine/dbal ≥3.5 在 change() 字段时重建表导致——含外键字段应避免直接 change，改用 dropColumn + addColumn 组合
- 模型工厂语法：从类工厂（Factory 类）全面转向闭包定义，旧工厂需重写
- 配置文件结构调整：如 config/logging.php 在 Laravel 9 中已重构，Laravel 11 又进一步精简了 app/Providers 目录结构
升级后不可跳过的验证动作
不测试就上线等于埋雷：
- 清除全部缓存：php artisan config:clear && php artisan route:clear && php artisan view:clear && php artisan cache:clear
- 运行全部测试：vendor/bin/phpunit，特别关注涉及中间件顺序、表单验证、队列 job 序列化的 Feature 测试
- 手动验证核心链路：登录、权限跳转、审批流提交、签名邮件链接、定时任务触发等高频业务场景
- 检查日志与异常页面：启用 APP_DEBUG=true 查看是否出现未捕获的 Target class does not exist 或 Class not found 错误
不复杂但容易忽略。
