生产环境升级Laravel 11必须严格遵循分支隔离、依赖锁定、结构迁移、缓存重建四步闭环：先确认PHP≥8.2且逐主版本升级（如9→10→11），再新建Git分支、同步更新composer.json中框架及配套包版本，运行php artisan upgrade迁移结构，最后清理并重建缓存、验证测试与数据库迁移。
生产环境升级 Laravel 11 必须在不中断服务的前提下完成，需严格遵循分支隔离、依赖锁定、结构迁移、缓存重建四步闭环，跳过任一环节都可能引发 500 错误或路由失效。
环境确认与分支隔离
先用 php -v 确认当前 PHP 版本 ≥ 8.2，低于则停止操作——Laravel 11 启动时直接拒绝加载，不会报错只会返回空白页。
运行 php artisan --version 查看当前 Laravel 版本，若为 9.x 或更早，【必须先升至 10.x 再升 11.x】，跨版本升级会导致中间件组解析失败、工厂类无法 autoload。
执行 git checkout -b prod-upgrade-11 新建独立分支，所有操作在此分支进行，避免污染 main 分支。
完整备份数据库 + .env + config/ 目录，用 mysqldump 导出 SQL 并本地保存，别只靠 Git 提交。
composer.json 更新与依赖拉取
打开 composer.json，修改 require 区域：
"php": "^8.2" → 必须显式声明，否则 Composer 可能忽略实际 PHP 版本，安装后运行时报 ParseError；
"laravel/framework": "^11.0" → 同时更新配套包："laravel/sanctum": "^4.0"、"spatie/laravel-ignition": "^2.4"、"nunomaduro/collision": "^8.1"；
删掉所有 "illuminate/*" 手动引入项——Laravel 11 已统一由框架内核管理，保留会导致 Class not found。
保存后执行：composer update --with-all-dependencies，加这个参数才能强制刷新子依赖树，否则 laravel/pint 等 dev 包可能卡在旧版引发冲突。
结构性变更处理
第一步：安装升级工具composer require laravel/upgrade --dev
第二步：执行自动迁移php artisan upgrade —— 这会删除空的 app/Http/Controllers、app/Providers 目录，并重写 app/Kernel.php 中的 $middlewareGroups 结构。
第三步：手动检查三处关键文件
① config/app.php：移除已废弃的 Illuminate\Pagination\PaginationServiceProvider::class 等行，残留会导致启动时报 Target class [PaginationServiceProvider] does not exist；
② database/factories：所有工厂类必须改为闭包写法，例如 UserFactory::new()->count(3)->create()，旧的 class UserFactory extends Factory 语法彻底失效；
③ app/Providers/AppServiceProvider.php：检查 register() 方法中是否用了 $this->app->bind() 的老写法，推荐改用 $this->app->extend() 避免绑定冲突。
缓存清理与上线验证
清空全部缓存：php artisan config:clear && php artisan cache:clear && php artisan view:clear && php artisan route:clear。
生成新缓存：php artisan config:cache && php artisan route:cache && php artisan view:cache —— 【必须在 APP_ENV=production 下执行】，否则 route:cache 会跳过中间件绑定导致登录路由失效。
运行测试套件：php artisan test --testsuite=Feature，重点验证用户认证、邮件发送、队列任务触发三个路径。
在预发布环境部署并手动触发一次 php artisan backup:run（若使用 spatie/laravel-backup），确认第三方集成无中断。
执行 php artisan migrate --force 同步数据库变更，注意检查是否有新增的 migration 文件需要人工干预字段类型。
