必须逐主版本升级，不可跳步；需确认当前版本、php≥8.2、第三方包兼容性，同步更新composer.json中框架及生态包版本，执行php artisan upgrade迁移结构，清理缓存并全面测试验证。
要把一个旧 Laravel 项目升级到 Laravel 11，必须先确认当前版本是否支持跳升、PHP 是否达标、第三方包是否兼容，否则 composer update 会卡住或 artisan 启动失败，甚至导致线上服务中断。
确认当前版本与升级路径
运行 php artisan --version 查看当前 Laravel 版本；若显示 【Laravel 9.x 或更低】，不能直接升 11，必须先升 10 再升 11。跳过中间主版本会导致 illuminate/support 版本撕裂、Facade 类找不到、中间件注册异常等静默崩溃。
打开 composer.json，检查 "php" 字段值：Laravel 11 强制要求 【^8.2】，若当前是 "^8.0" 或 "^8.1"，必须先升级 PHP 环境，否则 Composer 会降级安装旧版依赖，表面成功实则埋雷。
执行 composer outdated "laravel/*"，快速扫出所有 Laravel 官方包的滞后状态，比如 laravel/sanctum 若仍是 ^3.2，升 11 后会报 Class not found。
备份与分支隔离
用 Git 创建新分支：git checkout -b upgrade-to-11，避免污染 main 分支。
完整备份三样东西：composer.lock 文件、config/ 目录全量、数据库 dump 文件——【尤其 config/app.php 和 .env，升级脚本可能静默覆盖它们】。
把当前能跑通的所有测试用例再跑一遍：php artisan test 或 vendor/bin/phpunit，确保 baseline 是绿的，否则升级后无法判断问题来源。
更新 composer.json 并拉取依赖
方法一：手动编辑
打开 composer.json，在 "require" 区块中同步修改以下几项：
"laravel/framework": "^11.0"-
"php": "^8.2"（必须显式声明，不能省略） "laravel/sanctum": "^4.0""nunomaduro/collision": "^8.1""spatie/laravel-ignition": "^2.4"
若项目用了 Passport、Telescope、Cashier 等，也需按官方文档对应升级到 12.x / 5.x / 15.x 等兼容版本，漏掉任一关键包都会让 php artisan 报错退出。
保存后运行：composer update --with-all-dependencies。加这个参数是为了防止 illuminate/* 子包被锁在旧版，这是跨主版本升级最常踩的坑。
方法二：一键替换（适合从 Laravel 10 升级）
执行：composer require laravel/framework:^11.0 laravel/sanctum:^4.0 nunomaduro/collision:^8.1 --update-with-all-dependencies，Composer 会自动合并并重算依赖树，比手动改 JSON 更安全。
执行结构迁移与代码修正
第一步：装升级助手
composer require laravel/upgrade --dev
第二步：运行自动迁移
php artisan upgrade
这一步会重写 app/Providers/HttpKernel.php、清理废弃的 $middlewareGroups 键、调整路由服务提供者结构、移除 app/Http/Controllers 等目录——Laravel 11 默认不生成这些目录，靠命令补全，不是手动复制粘贴。
第三步：手动检查三项关键变更
① 搜索项目中所有 str()、array_* 辅助函数调用，全部替换成 Str:: 或 Arr:: 命名空间调用，例如 str_slug() → Str::slug()；
② 检查 config/app.php 中是否还残留 'providers' => [App\Providers\AppServiceProvider::class] 这种写法——Laravel 11 推荐全路径且部分提供者已自动注册，重复声明会报 Provider already registered；
③ 若用了 Sanctum、Passport、Telescope，必须手动发布迁移：php artisan vendor:publish --tag=sanctum-migrations → php artisan vendor:publish --tag=passport-migrations → php artisan vendor:publish --tag=telescope-migrations。这些包不再自动加载迁移，漏掉就建不了 auth_tokens 表。
验证与上线前收尾
清空全部缓存：php artisan config:clear && php artisan cache:clear && php artisan view:clear && php artisan route:clear。
重建自动加载映射：composer dump-autoload -o。
触发一次真实业务链路：登录 → 提交表单 → 发送邮件 → 推送队列任务，确认第三方集成未中断。
在预发布环境挂载日志监控，重点盯 Deprecated: 和 Undefined array key 类警告，这类问题不会立即报错但会在某次请求中突然崩掉。
准备好回滚命令：git checkout main && composer install && php artisan migrate:rollback。
