ThinkPHP 5.1不可直接升级至8.0，必须先升至6.1+再迁移到8.0；需严格验证CLI与Web SAPI的PHP版本一致性（均≥8.0.0）、必需扩展启用、代码层create_function/each/字符串下标等兼容性问题，并全面测试核心链路。
ThinkPHP 5.1 直接升级到 8.0 不可行——这不是版本号跳变，而是框架代际断裂。必须先升至 6.x（推荐 6.1+），再迁移到 8.0。前置检查不是走流程，而是识别哪些地方一动就崩。
确认当前基础环境是否真正就绪
很多“升级失败”其实卡在环境错位：CLI 用 PHP 8.2，Web SAPI 却跑着 7.4 的 php-fpm。这种双版本不一致会导致 composer update 成功、浏览器访问直接 500，且错误日志里只显示空白页或 500 而无具体线索。
- 执行 php think version 确认当前是 v5.1.x（非 5.0 或 5.2）
- 运行 php -v 查 CLI 版本，另建 info.php（
<?php phpinfo(); ?>）访问查 Web SAPI 版本，两者必须同时 ≥ 8.0.0 - 检查必需扩展是否启用：mbstring、openssl、pdo_mysql、json、curl（缺一不可，尤其 mbstring 是路由和验证模块的底层依赖）
- 确认 mbstring.func_overload = Off（PHP 7.2+ 已废弃该配置，开启会导致 URL 解析错乱、中文字段匹配失败）
扫描代码层兼容性风险点
TP 5.1 的语法和调用习惯与 8.0 完全不兼容，但很多问题不会立即报错，而是静默失效——比如 each() 循环被跳过、create_function() 导致缓存模块彻底失能。
- 全局搜索 create_function( —— 主要集中在
thinkphp/library/think/Cache.php，至少 3 处，全部需改为匿名函数 - 搜索 each( —— 重点检查
Db.php和Model.php，替换为foreach ($arr as $k => $v)；自定义 Model 子类中若有 also 需同步改 - 执行 grep -r "\$\w\+{\d\+}" thinkphp/ 找字符串偏移语法（如
$str{0}），替换为strlen($str) ? $str[0] : '' - 检查是否手动调用过时 MySQL 函数（
mysql_connect等），PHP 8.0+ 已彻底移除，必须转为 PDO 或\think\Db::接口
评估第三方依赖与业务耦合度
升级不是改框架，而是重校准整个技术栈。很多崩溃源于第三方包没跟上 PHP 8.0+ 的语义变化，而非 ThinkPHP 本身。
立即学习“PHP免费学习笔记（深入）”；
- 运行 composer show --tree | grep -E 'think|topthink' 查看框架及插件真实版本，警惕混用多个 ThinkORM 版本
- 检查 jwt-auth、alipay-sdk、wechat-sdk 等常用 SDK 是否标注支持 PHP 8.0+；不支持的需替换或打补丁
- 统计自定义行为（behavior）、标签库（taglib）、中间件中硬编码调用
think\App、think\Request等类的地方——TP 8.0 中这些类路径和初始化方式已重构 - 确认数据库配置中是否含连接池、读写分离等高级参数，TP 6+/8.0 的 Db 类对这些参数的解析逻辑有调整
验证测试与回滚准备
没有测试覆盖的升级等于盲拆承重墙。TP 5.1 到 8.0 的跨度意味着大量 Facade、路由、验证器、模型关联逻辑变更，仅靠肉眼 review 不可靠。
- 检查核心业务接口是否有自动化测试（尤其是登录、支付、订单创建等链路），覆盖率低于 60% 建议先补关键用例
- 备份完整
config/和app/目录，记录各配置项 MD5 值，便于快速比对差异 - 清理
runtime/目录（升级后必删，否则旧缓存会干扰新路由和模板编译） - 本地用
docker run -it --rm -v $(pwd):/app -w /app php:8.2-cli composer update模拟升级过程，提前暴露依赖冲突
