Laravel 11 升级需分三步：先确认环境（PHP ≥8.2）、备份并新建分支；再更新 composer.json 及依赖，运行 php artisan upgrade 迁移结构；最后验证缓存、测试、集成与日志，准备回滚。
直接升级 Laravel 到最新主版本不是改个数字就完事，关键在控制风险、适配变更、验证结果。Laravel 11 是当前最新稳定版（截至 2025 年底），它对 PHP 8.2+ 有硬性要求，且结构精简、内核重构，跳过中间版本容易出问题。
先确认环境和备份
这是所有操作的前提，不能省略：
- 运行 php -v 确认 PHP 版本 ≥ 8.2；低于则先升级 PHP
- 执行 php artisan --version 查看当前 Laravel 版本，判断升级跨度（例如从 9 → 11 就不建议跳过 10）
- 用 git checkout -b upgrade-to-11 新建分支，避免污染主干
- 完整备份代码 + 数据库 + config/ 和 .env 文件
更新 composer.json 并拉取依赖
核心是让 Composer 解析新版依赖树，同时兼顾生态包兼容性：
git-staged-commit-message
下载
仅从仓库的暂存文件生成 Git 提交消息。当用户要求 Codex 根据暂存更改、缓存差异、Git 索引或已通过 `git add` 添加的文件来编写、起草、创建或建议提交消息时使用；切勿代表用户执行提交操作。
- 打开 composer.json，修改 "laravel/framework": "^11.0"（原为 ^10.0 或更低）
- 同步更新配套包：如 "laravel/sanctum": "^4.0"、"spatie/laravel-ignition": "^2.4"、"nunomaduro/collision": "^8.1"
- 检查 "php" 行是否已改为 "^8.2"，否则 Composer 会拒绝安装
- 保存后运行 composer update --with-all-dependencies，避免部分包被锁死
处理结构性与代码级变更
Laravel 11 引入了轻量应用结构，默认不生成 app/Http/Controllers 等目录，还需调整多处逻辑：
- 运行 php artisan upgrade（需先 composer require laravel/upgrade --dev），自动迁移目录结构和配置
- 检查 AppServiceProvider：register/boot 方法签名未变，但部分绑定方式推荐改用容器扩展
- HTTP 内核中中间件组定义方式简化，旧的 $middlewareGroups 需按新模板重写
- 移除所有 illuminate/* 的手动 require（Laravel 11 已统一由框架管理）
- 搜索项目中 str()、array_* 辅助函数调用，替换为 Str:: 或 Arr:: 命名空间调用
验证与上线前收尾
升级完成≠可用，必须逐层验证：
- 清空缓存：php artisan config:clear && php artisan cache:clear && php artisan view:clear
- 运行全部测试：phpunit 或 php artisan test，重点关注认证、队列、API 响应
- 手动触发一次备份、邮件通知、队列任务，确认第三方集成未中断
- 在预发布环境跑 24 小时，监控日志中的 Deprecated 和 Undefined array key 类警告
- 准备好回滚命令：git checkout main && composer install && php artisan migrate:rollback
基本上就这些。不复杂但容易忽略细节，尤其是跨大版本时的配置迁移和第三方包适配。官方 UPGRADING.md 和 changelog.md 比任何教程都准，建议边操作边对照着看。
