ThinkPHP升级或切换PHP版本报错，核心是框架、扩展、语法三者未对齐；需按四步排查：一查真实PHP环境（php -v/--ini/-m），二修扩展配置（如移除mbstring.func_overload、禁用mysql_*函数），三核框架兼容性（TP5.1需≥v5.1.42适配PHP8.2，TP6.3不支持PHP8.3+，TP8.x强制PHP≥8.0），四速查典型错误并修复（如Class 'think\App' not found执行composer install --no-dev）。
ThinkPHP 项目升级或切换 PHP 版本时，报错往往不是代码写错了，而是框架、扩展、语法三者没对齐。核心思路是：先定位冲突层（PHP 版本？扩展缺失？框架旧？），再按层修复，不跳步、不硬扛。
第一步：确认真实 PHP 环境
别信面板显示，用命令看实际运行环境：
- 执行 php -v，确认是 PHP 7.4 / 8.0 / 8.1 / 8.2 还是 8.3——TP6.3 不支持 8.4，TP5.1 在 8.2 下必须打补丁
- 执行 php --ini，记下加载的 php.ini 路径，后续所有配置修改都得改这个文件
- 执行 php -m | grep -E 'pdo|mbstring|xml|zip|openssl'（Linux/macOS）或 php -m | findstr /i "pdo mbstring xml zip openssl"（Windows），缺一不可——漏 xml 会导致 Excel 导入直接 Fatal error
第二步：关键扩展与配置修正
新版 PHP 默认关闭或废弃某些旧行为，必须手动对齐：
-
mbstring.func_overload：PHP 8.0+ 已彻底移除该配置。若 php.ini 中还留着
mbstring.func_overload = 2，Excel 读中文列名会返回空，且无提示。直接删掉或注释这一行 -
mysql_* 函数：PHP 8.2+ 已完全删除。全局搜索
mysql_connect、mysql_query，全部替换为\think\Db::query()；同时检查config/database.php中'type'必须是'pdo_mysql'，不能是'mysqlnd'或'mysql' -
内存限制写法：PHP 8.2 解析更严格，
ini_set('memory_limit', '256M')可能失效，建议改为ini_set('memory_limit', '-1')（开发阶段临时用）
第三步：框架版本与依赖对齐
不同 ThinkPHP 版本对 PHP 有硬性要求，混用必出问题：
立即学习“PHP免费学习笔记（深入）”；
-
TP5.1：最低适配 PHP 7.1，但 PHP 8.2 下需升级到
v5.1.42+才修复动态属性警告；否则所有未声明的$this->data都会触发Deprecated: Creation of dynamic property -
TP6.x：推荐 PHP 7.4–8.2。TP6.3 支持 PHP 8.2，但不支持 8.3+；若用 Excel 导入，必须换
phpoffice/phpspreadsheet:^1.29.0（^2.0要求 PHP 8.3+，且删了常用方法） -
TP8.x：强制要求 PHP ≥8.0，镜像必须用
php:8.1-cli或更高，PHP 7.4 直接 Parse error
第四步：常见报错速查与修复
遇到报错别猜，对照典型症状快速处理：
-
Class 'think\App' not found：Composer 没装全或 vendor 未生效。运行
composer install --no-dev，确认vendor/autoload.php可被正常引入 -
Deprecated: array_key_exists(): Argument #2 must be of type array|object：TP5.1 的验证器中传了
null。修复方式：在调用前加is_array($data) && array_key_exists(...)，或升级到v5.1.43+ -
Fatal error: Uncaught Error: Call to undefined function each()：PHP 8 删除了
each()。把list($k, $v) = each($arr)全部换成foreach ($arr as $k => $v)或 PHP7.1+ 的数组解构[$k, $v] = $arr -
首页能打开，但 /index/index 报 404：伪静态未生效。检查 Nginx 是否设置了
try_files $uri $uri/ /index.php?$query_string;，且站点运行目录设为/public
