Laravel 11升级必须完成环境确认、依赖更新、结构迁移、代码适配和功能验证五步：先验PHP≥8.2及框架版本，创建分支并备份；再更新composer.json约束，强制刷新依赖；接着用laravel/upgrade执行结构迁移；然后修正工厂语法、中间件组和辅助函数调用；最后清缓存、跑测试、监控24小时。
将 Laravel 项目升级到 11.x 版本必须完成环境确认、依赖更新、结构迁移、代码适配和功能验证五个不可跳过的环节，漏掉任一环节都可能导致 artisan 命令崩溃、中间件失效或路由 404；当前 Laravel 11 是唯一受支持的 LTS 版本（支持至 2027 年），但若你正运行 9.x 或更早版本，必须先升至 10.x 再升 11.x，跨主版本操作会直接触发 illuminate/support 版本撕裂。
确认当前状态与创建安全分支
先别碰 composer.json —— 运行 php artisan --version 查看实际框架版本，再执行 php -v 确认 PHP 是否 ≥ 8.2；若输出为 PHP 8.1.28，必须先升级 PHP，否则后续所有 composer 命令都会静默装错依赖。
用 git 创建独立升级分支：git checkout -b upgrade-to-11，然后完整备份 config/、.env 和数据库 dump 文件——这一步不能省，【回滚时只靠 git checkout main 不够，缺数据库备份等于丢数据】。
运行 composer outdated "laravel/*" 扫描所有第一方包滞后情况，重点关注 laravel/sanctum 是否低于 ^4.0、spatie/laravel-ignition 是否低于 ^2.4。
修改 composer.json 并拉取新版依赖
打开 composer.json，在 "require" 区块中同步修改以下三项：
把 "laravel/framework": "^10.0" 改为 "laravel/framework": "^11.0"；
把 "php" 行显式补全为 "php": "^8.2"，否则 Composer 可能沿用旧约束，导致装出不兼容的 illuminate 子包；
把 "nunomaduro/collision": "^6.1" 升为 "^8.1"，"spatie/laravel-ignition": "^1.0" 升为 "^2.4"，"laravel/sanctum": "^3.2" 升为 "^4.0"。
保存后执行 composer update --with-all-dependencies，加这个参数才能强制刷新整棵依赖树，避免部分包被锁在旧版引发 Target class does not exist 错误。
执行结构迁移与目录重建
第一步：安装升级助手：composer require laravel/upgrade --dev；
第二步：运行迁移命令：php artisan upgrade；
第三步：它会自动重写 app/Providers/HttpKernel.php、清理废弃的 $middlewareGroups 键、补全缺失的 app/Http/Controllers 目录——【不要手动创建这些目录，否则 AppServiceProvider 中的容器绑定逻辑会因签名未变但实现已重构而解析失败】。
迁移完成后检查 config/app.php，删掉残留的 'providers' => [App\Providers\AppServiceProvider::class] 这类数组声明，Laravel 11 已改为自动注册命名空间全路径服务提供者，重复声明会报 Provider already registered。
手动核对关键变更点
方法一：工厂文件语法
打开 database/factories 下所有文件，把旧式类定义 class UserFactory extends Factory 全部替换为闭包写法：use Illuminate\Database\Eloquent\Factories\Factory; → return new Factory(...)；否则启动时直接报 Class "UserFactory" not found。
方法二：中间件组配置
对比官方 11.x 文档中的 app/Providers/HttpKernel.php 模板，确认 web 组是否还包含 EncryptCookies::class 和 StartSession::class；Laravel 11 默认移除了它们，如果你的登录态或 CSRF 依赖这些，必须手动加回去。
方法三：辅助函数调用
全局搜索项目中所有 str()、array_* 调用，替换成 Str:: 和 Arr:: 命名空间调用；Laravel 11 不再自动加载这些辅助函数，不改就会出现 Call to undefined function str()。
验证与上线前收尾
清空全部缓存：php artisan config:clear && php artisan cache:clear && php artisan view:clear；
重建自动加载映射：composer dump-autoload；
运行全部测试：php artisan test，重点观察认证流程、队列任务触发、API JSON 响应格式是否异常；
手动触发一次邮件发送和数据库备份任务，确认第三方集成链路未中断；
在预发布环境持续运行 24 小时，监控日志中是否出现 Deprecated 或 Undefined array key 类警告。
