Linux服务器上 ThinkPHP 版本升级实操指南
一 升级前准备
- 备份与版本确认：先对代码与数据库做完整备份（含配置文件、附件、上传目录、定时任务脚本等），记录当前框架与依赖版本。命令示例：查看 ThinkPHP 版本可用php think version；查看 PHP 版本用php -v；查看已安装依赖用composer show。升级前务必确认目标版本的PHP 最低版本要求与扩展依赖（如PDO、Mbstring等）已满足。
- 运行环境：优先在测试环境完成升级演练，再同步到生产；升级期间建议开启维护页或维护模式，避免业务写入。
- 升级策略：小版本建议就地升级（composer 直接更新）；跨大版本（如5→6、6→8）建议新建目标版本项目并迁移（更安全可控）。
二 就地升级步骤（同大版本内，如 6.x → 6.y 或 5.1.x → 5.1.y）
- 步骤1 环境校验：确认当前 PHP 版本满足目标版本要求，安装缺失扩展（如PDO、Mbstring），并确保Composer可用。
- 步骤2 小版本升级：在项目根目录执行composer update topthink/framework（或带版本约束如composer require topthink/framework:^6.0）。注意：部分 6.x 小版本升级时仅更新 framework 可能报错，建议直接执行不带包名的composer update以统一解析依赖。
- 步骤3 清理与验证：升级后清理runtime缓存目录，使用php think version确认版本；访问关键业务链路与后台，观察日志与异常。
- 步骤4 多环境一致性：同步更新测试、预发与生产环境的composer.lock与依赖，避免环境漂移。
三 跨大版本升级路径（如 5.1 → 6.0、6.x → 8.0）
- 推荐做法：新建目标版本项目，再迁移业务代码与数据。
- 新建目标版本：执行composer create-project topthink tp8（示例为 8.0），参考其composer.json获取目标版本的依赖约束（如topthink/framework:^8.0、topthink-orm:^3.0、topthink-filesystem:^2.0）。
- 合并代码：将旧项目的应用代码（控制器、模型、服务、验证器、视图、静态资源等）迁入新项目对应位置；按需调整命名空间与目录结构差异。
- 迁移配置与路由：对照新旧版本的config/、route/ 变更，更新数据库配置、缓存/会话/日志、中间件与路由定义。
- 依赖对齐：在旧项目根目录按目标版本调整composer.json（参考新建项目的依赖），必要时删除composer.lock后执行composer install以重建依赖锁。
- 数据库与第三方库：检查ORM/查询构造器用法差异，运行迁移/填充脚本，升级或重装第三方包并回归测试。
- 验证与切换：清理runtime，开启调试查看错误详情，完成回归后切换到新版本入口并观察线上日志。
- 替代方案（不推荐用于复杂项目）：使用在线升级脚本（如将 updateTP.php 放入 public 后访问执行），务必先备份并先在测试环境验证。
四 升级后检查清单
- 配置与目录：核对config/app.php、config/database.php、route/ 等关键配置；确保public为对外访问目录，目录权限与所有者正确。
- 依赖与扩展：确认所有第三方库与新版本兼容，必要时升级；检查PHP 扩展（PDO、Mbstring、openssl 等）已启用。
- 缓存与生成：清理runtime与模板缓存，必要时重新生成；访问首页与后台，验证路由、登录、上传、支付/消息队列等核心链路。
- 安全与性能：启用或调整CSRF、请求限制、日志与监控等安全配置；评估并应用新版本带来的性能优化。
五 常见问题与处理
- 仅更新 framework 报错：部分 6.x 小版本升级需统一解析依赖，直接执行composer update更稳妥。
- PHP 版本不匹配：跨大版本常伴随PHP 最低版本提升（如 TP8 要求PHP >= 8.0），需先升级 PHP 并重启 php-fpm（如systemctl restart php-fpm），再执行升级。
- 缓存与目录残留：升级后务必清理runtime；如采用替换核心目录方式升级，也需清理旧缓存。
- 回退方案：升级异常时，立即切回备份或Git 回退到升级前提交，定位问题后再重试。
