CentOS 中 Laravel 版本升级步骤
一 升级前准备
- 备份关键资产：全量备份代码、.env、数据库（如 mysqldump）、存储目录 storage/ 与 public/storage，并准备可快速回滚的方案。
- 检查当前版本与环境：在项目根目录执行 php artisan --version；确认 PHP 版本与扩展（如 openssl、pdo、mbstring、tokenizer）满足目标 Laravel 的要求；同时将 Composer 更新到最新：composer self-update。
- 选择升级策略：小版本（如 9.x → 9.y）可在原项目就地升级；大版本（如 8.x → 9.x）建议新建 Laravel 12 项目并迁移业务代码与配置，风险更低。
- 阅读变更与升级说明：对照目标版本的 UPGRADE.md/CHANGELOG.md，梳理破坏性变更与废弃 API。
- 在开发/预发布环境演练：先在测试环境完成全流程验证，再进入生产。
二 小版本就地升级步骤（同主版本，如 9.x → 9.y）
- 进入项目根目录并更新依赖：
- 更新框架：composer update laravel/framework
- 或整体更新：composer update（注意锁文件变更与稳定性）
- 执行升级命令与优化：
- 若有可用升级命令：php artisan upgrade
- 清缓存与自动加载：php artisan config:clear && php artisan route:clear && php artisan view:clear && composer dump-autoload
- 数据库与静态资源：
- 执行迁移：php artisan migrate（必要时先 php artisan migrate --pretend 预演）
- 发布/修复静态资源链接：php artisan storage:link
- 前端资源（如使用 Mix/ Vite）：npm install && npm run build
- 验证：功能回归与自动化测试，观察 storage/logs/laravel.log 无异常。
三 大版本跨级升级步骤（如 8.x → 9.x 或 9.x → 10.x/11.x/12.x）
- 新建目标版本项目并同步业务代码：
- 创建新项目：composer create-project laravel/laravel project-new “12.*”（版本号按目标选择）
- 将旧项目的 app/（业务代码）、routes/、config/（按需）、以及自定义的 resources/、public/ 资源迁入新项目。
- 对齐依赖与框架版本：在 composer.json 将 laravel/framework 与关键依赖（如 PHP 约束、第三方包）调整到目标版本兼容范围，然后 composer update。
- 配置迁移与校验：
- 对比并合并配置（优先使用新版本配置模板，手动迁移自定义项），执行 php artisan config:clear 后再 php artisan config:cache。
- 处理队列、邮件、缓存、日志等驱动变更与新增配置。
- 数据库迁移与数据变更：
- 执行迁移：php artisan migrate；如有数据结构大幅调整，按需在迁移中编写数据迁移脚本。
- 静态资源与前端：重新安装依赖并构建：npm install && npm run build。
- 验证与回滚预案：全量回归测试，确认无破坏性变更后再切流量。
四 升级后验证与常见问题处理
- 验证清单：
- 路由与中间件注册、权限与认证、队列与计划任务、邮件与通知、第三方包功能、API 响应与错误日志。
- 执行：php artisan test、查看 storage/logs/、必要时开启 APP_DEBUG=true 于测试环境定位问题。
- 常见问题与修复：
- Composer 依赖冲突：使用 composer depends laravel/framework 分析依赖树，按目标版本约束调整版本；必要时分步更新或临时使用 –no-scripts 完成解析后再恢复脚本。
- 配置冲突：用新版配置模板对比迁移，避免直接覆盖；变更后执行 config:clear 与 config:cache。
- 路由/代码废弃：按 UPGRADE.md 替换废弃语法（如路由命名空间字符串语法改为类引用），并更新相关调用。
- 静态资源与软链：确认 public/storage 正确链接，执行 storage:link；前端资源重新构建。
- 迁移失败：先 migrate --pretend 检查 SQL，再分批执行或编写数据迁移脚本。
五 生产环境发布与回滚建议
- 灰度与回滚：先在预发布/灰度环境验证，使用负载均衡或反向代理逐步切流；保留旧版本可快速回滚（代码与数据库备份、可回滚的迁移脚本）。
- 维护窗口与通知：选择低峰期发布，提前通知业务方；执行期间监控 日志与队列。
- 自动化与工具：在复杂升级或跨多版本时，可考虑使用 Laravel Shift 等自动化工具降低人工成本与风险。
