老项目升级ThinkPHP核心在于值不值得升、升了稳不稳，必须先验证新环境运行基础、锁定PHP与扩展边界、列出高频不兼容API，确保“运行通、依赖齐、接口清”三件事到位后再动业务代码。
老项目升级 ThinkPHP，核心不是“能不能升”，而是“值不值得升、升了稳不稳”。直接上新版本改代码，大概率踩进白屏、报错、数据错乱的坑。真正有效的升级路径，是把验证放在动手之前——先让系统在新环境下跑起来，再逐层确认改动影响。
先跑测试：用最小改动验证运行基础
拿到新框架包或执行 composer update 后，别急着改业务逻辑。目标很明确：让首页和登录页能正常打开，数据库能连上，关键路由不 404。
- 保持原有入口文件（如 public/index.php）和配置结构不变，只替换框架核心目录或更新 vendor 中的 thinkphp 包
- 关闭所有自定义中间件、钩子、扩展，避免干扰基础请求生命周期
- 临时启用调试模式（APP_DEBUG = true），捕获 PHP 报错、Deprecated 警告、未定义方法等第一手线索
- 重点观察日志：runtime/log/ 下的错误时间戳是否集中、是否重复出现某类异常（比如 mysql_connect 已废弃 或 preg_replace /e 修饰符不支持）
锁依赖：明确 PHP 版本与扩展边界
ThinkPHP 不同版本对底层环境有硬性要求，跳过这步等于在雷区蒙眼走路。
- TP3.1.3 适配 PHP 5.2–5.6，TP5.1 推荐 PHP 7.1–7.4，TP8.0+ 强制要求 PHP 8.0+；跨代升级必须同步调整 PHP 运行时
- 检查扩展是否就位：TP5.1 仍可用 mysql 扩展，TP8 则只支持 pdo_mysql；mbstring、openssl、json 是全版本刚需
- 用 composer install --ignore-platform-reqs 强行安装只是临时绕过，不能替代真实环境适配；上线前必须在目标 PHP 版本下完整走通
列不兼容 API：聚焦高频破坏性变更
不是所有函数都变了，但几个关键点一旦忽略，就会导致功能静默失效。
立即学习“PHP免费学习笔记（深入）”；
- 模型时间戳字段：TP5.0 默认开启自动写入 create_time/update_time，TP5.1 开始默认关闭，需显式设置 protected $autoWriteTimestamp = true
- 查询构造器链式调用：TP5.1 中 where('id', $id) 和 where(['id' => $id]) 行为一致；TP8 支持命名参数（如 ->where(field: 'status', value: 1)），但旧写法仍兼容
- 配置加载优先级：TP5.1 引入 .env 文件机制，会覆盖 config/ 下的 PHP 配置；老项目若没迁移 .env，可能造成数据库账号、缓存开关等配置被意外覆盖
- 路由定义语法：TP3.x 的 __URL__/User/index 模板变量在 TP5+ 中已移除；TP5.1 使用 url('user/index')，TP8 支持更严格的资源路由声明，旧路由规则需重写
升级不是版本号变大就万事大吉。真正决定成败的，是有没有把“运行通”“依赖齐”“接口清”这三件事，在动一行业务代码前就确认到位。
