Laravel 11升级必须逐主版本推进,不可跳步;需先确认当前版本(php artisan --version)、PHP≥8.2、依赖兼容性,再修改composer.json、更新依赖、迁移结构、清理缓存并全面测试验证。

将 Laravel 项目从旧版本平稳升级至 11.x,需严格按主版本顺序推进、分阶段验证关键节点、控制每轮升级耗时在可接受窗口内,避免因跨版本跳升或环境不匹配导致服务中断或数据异常。
确认当前版本与目标路径
运行 php artisan --version 查看当前 Laravel 版本,再查 composer.json 中 "laravel/framework" 的实际值——Artisan 命令可能已失效,但 composer.json 永远真实。
若当前为 9.x,必须走 9 → 10 → 11 路径;若已是 10.x,则直接规划 10 → 11 升级;【跳过 10.x 直接升 11.x 会导致中间件注册失败、路由加载错乱、artisan 命令无法启动】。
访问 Laravel 官方 Upgrade Guide: 11.x 页面,确认你正在查阅的是「10.x to 11.x」章节,不是「9.x to 11.x」的合并指南。
环境与依赖预检
执行 php -v,输出必须为 PHP 8.2.x 或更高;低于则终止流程,先升级 PHP。
运行 php -m | grep -E 'mbstring|openssl|pdo|xml|ctype|json|tokenizer',缺任一扩展,php artisan 启动即报错且错误堆栈藏在末尾,容易误判为代码问题。
检查 composer.json 中 "php" 字段是否已显式写为 "^8.2";未声明时 Composer 可能沿用旧约束,导致安装降级依赖,后续 composer update 表面成功实则埋雷。
分支创建与备份
第一步:用 git checkout -b upgrade-to-11-202608 新建带日期标识的升级分支,避免污染 main。
第二步:导出数据库全量备份(含结构+数据),保存为 backup-20260806.sql;同时复制 .env 和 config/ 全目录到安全位置。
第三步:提交当前全部变更到该分支,确保 Git 历史可回溯;这一步漏做,升级中途出错将无法精准还原到“刚改完 composer.json”的状态。
composer.json 修改与依赖更新
方法一:手动编辑 composer.json
将 "laravel/framework": "^10.0" 改为 "^11.0";同步更新配套包:"spatie/laravel-ignition": "^2.4"、"nunomaduro/collision": "^8.1"、"phpunit/phpunit": "^10.5"(注意不是 ^11.0)。
方法二:批量校验第三方包兼容性
Laravel Cloud(cloud.laravel.com)。此技能用于处理所有 Laravel Cloud 请求,包括搜索和读取数据。只要任务涉及 Laravel Cloud,即使用此技能。
运行 composer outdated "laravel/*",逐个比对输出列表中的包是否满足 11.x 要求;例如 laravel/sanctum 必须 ≥ 4.0,否则会抛 Class not found。
方法三:执行更新命令
composer update --with-all-dependencies —— 不加此参数,部分包会被锁在旧版,导致 php artisan 启动时报 Target class [App\Http\Kernel] does not exist 这类结构性错误。
结构迁移与代码适配
先运行 composer require laravel/upgrade --dev 安装升级助手,再执行 php artisan upgrade。它会自动删掉 app/Http/Kernel.php、重写 bootstrap/app.php、调整中间件注册方式。
检查 routes/web.php 和 routes/api.php 是否仍存在;Laravel 11 默认只加载 routes.php,残留旧文件会导致路由重复注册或 404,必须手动删除或注释掉原有 Route::get 调用。
打开 bootstrap/app.php,确认是否已包含 ->withMiddleware()、->withRouting()、->withExceptions()、->withProviders() 四个闭包;缺任一,对应功能(如中间件、路由分组、异常渲染、服务提供者)将完全失效,且无明确报错提示。
搜索项目中所有 str()、array_* 辅助函数调用,全部替换为 Str:: 或 Arr:: 命名空间调用;Laravel 11 已移除全局辅助函数,不改则运行时报 Call to undefined function。
验证与上线前收尾
清缓存三连:php artisan config:clear && php artisan cache:clear && php artisan view:clear;不执行,旧配置和视图仍将生效,掩盖升级问题。
运行全部测试:php artisan test,重点盯住认证流程、队列任务触发、API 响应结构是否符合预期;测试通过≠业务可用,必须人工走一遍登录→创建资源→触发邮件→消费队列全流程。
在预发布环境部署并持续观察 24 小时,用 tail -f storage/logs/laravel.log 监控日志,重点关注 Deprecated: 和 Undefined array key 类警告——它们不会中断请求,但预示着下个主版本将彻底报错。
准备好回滚命令:git checkout main && composer install && php artisan migrate:rollback;把这行命令复制进记事本,放在升级窗口开启前就备好。










