升级 laravel 11 必须在独立分支中完成：先创建并推送 upgrade/laravel-11 分支，再确保 main 分支最新后合并；推荐使用 --no-ff 三步合并以保留上下文，冲突需重点修正 config/app.php 等核心文件。
升级 Laravel 11 时必须在独立分支中完成全部操作，否则直接在 main 或 master 分支上执行 composer update 或 php artisan upgrade 会导致生产环境配置错乱、缓存失效、路由不可用，且无法快速回退。
创建并切换到专用升级分支
运行 git checkout -b upgrade/laravel-11 创建新分支。这一步不能省略，【Git 不会自动跟踪远程同名分支，需手动推送】。
立即运行 git push origin upgrade/laravel-11 将分支同步至远程仓库。若跳过此步，后续多人协作时他人无法基于该分支开展兼容性验证。
合并前确保主分支最新
切回主分支：git checkout main。
执行 git pull origin main 拉取线上最新代码。这一步漏掉会导致升级分支基于陈旧代码构建，后续合并时产生大量非必要冲突。
确认当前 main 分支 HEAD 与远程一致：git status 应显示 “Your branch is up to date with 'origin/main'”。
将升级分支合并回主分支
方法一：标准三步合并（推荐用于团队协作）
① 切换到 main 分支：git checkout main。
② 合并升级分支：git merge --no-ff upgrade/laravel-11。使用 --no-ff 强制生成合并提交，保留升级过程的完整上下文，便于日后审计。
③ 推送合并结果：git push origin main。
方法二：Rebase 后快进合并（仅限单人维护项目）
先切换到 upgrade/laravel-11 分支，运行 git rebase main；再切回 main，执行 git merge upgrade/laravel-11。该方式历史线性干净，但【rebase 会改写提交哈希，已推送的升级分支不可再被他人基于原提交继续开发】。
处理合并冲突
若 git merge 出现 CONFLICT (content) 提示，打开标红文件，查找 >>>>>> 标记段落。
重点检查 config/app.php、bootstrap/app.php、routes/web.php 等核心文件——Laravel 11 移除了 App\Http\Controllers 目录默认加载逻辑，此处冲突不手动修正会导致整个应用启动失败。
编辑完所有冲突文件后，逐个执行 git add 文件路径，最后 git commit 完成合并。
