在 Debian 上升级 ThinkPHP 的实操指南
一 升级前准备
- 备份与版本控制
- 备份整个项目代码与数据库；使用 Git 管理代码，升级前创建特性分支（如：upgrade/v6.1-to-v6.6），便于回滚与审查。
- 配置 .gitignore，忽略 /runtime/、/vendor/、/public/uploads/、.env 等；提交 composer.json 与 composer.lock，不提交 vendor/。
- 检查运行环境
- 确认 PHP 版本满足目标 ThinkPHP 的要求（如 ThinkPHP 8 需要 PHP >= 8.0），以及 Composer 可用。
- 依赖与扩展梳理
- 列出关键依赖（如 topthink/framework、topthink-orm、topthink-filesystem 等），升级后需同步检查其兼容性。
二 标准升级步骤
- 小步升级策略
- 避免跨多个大版本直接升级，优先逐级升级（如 6.0.x → 6.1.x → 6.6.x → 8.0.x），每一步都完成测试再进入下一步。
- 使用 Composer 升级（推荐）
- 仅升级框架包：在项目根目录执行 composer update topthink/framework，不要单独只升级 framework 的子包，以免产生依赖冲突。
- 跨大版本（如 6 → 8）：先在项目根目录调整 composer.json 的版本约束（例如 “topthink/framework”: “^8.0”、“topthink-orm”: “^3.0”、“topthink-filesystem”: “^2.0”），必要时删除 composer.lock 后执行 composer update 重新解析依赖。
- 非 Composer 项目（直接替换框架目录）
- 下载目标版本框架包，将项目中的 thinkphp/ 目录替换为新版本，注意保留你的应用目录（如 application/ 或 app/）与自定义配置，避免覆盖业务代码。
- 配置与代码适配
- 按目标版本的升级说明调整配置结构与代码（如配置项更名、废弃 API、路由规则变化等），并升级相关第三方扩展至兼容版本。
三 版本跨度与兼容性要点
- PHP 运行时要求
- 升级到 ThinkPHP 8 需 PHP >= 8.0；若当前环境为 PHP 7.x，需先在 Debian 上升级 PHP（如从 PHP 7.4 升级到 PHP 8.1/8.2），并重启 php-fpm 与 Nginx/Apache 使新版本生效。
- 框架与依赖版本
- 6.x 系列升级时，优先将 topthink/framework 升到该系列的最新稳定版；跨到 8.0 时，同步调整 think-orm 与 think-filesystem 等依赖版本，以匹配官方建议。
- 常见不兼容
- 可能出现函数/类废弃、参数变更、配置结构变化、路由规则调整及第三方扩展不兼容，需结合官方升级指南逐项修正并回归测试。
四 Debian 环境注意事项
- PHP 多版本切换与生效
- 使用 update-alternatives 切换 CLI 与 FPM 的 PHP 版本，或调整 php-fpm 的监听套接字与池配置；完成后重启服务：
- 示例：sudo systemctl restart php8.1-fpm 与 sudo systemctl restart nginx（或 apache2）
- 服务平滑切换
- 建议先在测试环境验证，再灰度/蓝绿发布；升级窗口内保持旧版本可快速回滚（代码回滚或 FPM 切回旧版本）。
- 文件与目录权限
- 确保 runtime/ 目录可写，Web 服务器用户（如 www-data）对相关目录具备读写权限，避免因权限问题导致页面白屏或日志写入失败。
五 升级后验证与回滚
- 版本与依赖核验
- 执行 php think version 查看框架版本；执行 composer show topthink/framework 等确认依赖版本；检查路由、数据库连接、缓存、日志是否正常。
- 全面回归测试
- 覆盖关键业务路径、后台管理、支付/登录、文件上传、第三方 API 调用等；关注废弃特性替换与异常日志。
- 快速回滚方案
- 代码回滚：git checkout 或 git revert 到升级前提交；依赖回滚：恢复 composer.json/composer.lock 并重跑 composer install；环境回滚：将 PHP-FPM 切回旧版本并重启服务。