ThinkPHP升级后报错主因是环境、路径、配置三者失配：TP6要求public为根目录，TP8.1需PHP≥8.1，伪静态未转发请求至index.php，或自动加载失效；须先验证是否进框架，再逐级排查Nginx规则、PATH_INFO传递、路由注册及autoload路径。
升级ThinkPHP版本后项目部署到服务器报错，不是代码写错了，而是新旧版本底层机制断裂导致环境、路径、配置三者失配——比如TP6要求public为根目录而你仍把整个项目设为网站根，或TP8.1依赖PHP 8.4但服务器只装了8.0，这类错位会直接触发500或Class not found。
第一步：确认是否真进了框架
浏览器访问 【http://你的域名/public/index.php】，看响应头里有没有 【X-Powered-By: ThinkPHP】。没有就说明PHP根本没接管请求，所有后续排查都是白忙。
如果连这个地址都空白或500，立刻检查PHP版本和扩展：运行 php -v 和 php -m | grep -E 'mbstring|pdo|openssl|curl|intl'，缺一个扩展就会让入口文件静默失败。
宝塔用户重点核对：软件商店→PHP→设置→安装扩展，必须手动勾选全部五项；Windows用户别用XAMPP自带旧版PHP，PDO常被默认禁用。
立即学习“PHP免费学习笔记（深入）”；
第二步：查伪静态有没有把请求转给index.php
方法一：绕过重写直击入口
访问 【http://你的域名/index.php/index/index】（TP6/TP8默认首页路由）。能打开 → 框架通，问题在Nginx/Apache重写规则；打不开 → 路由文件没加载或APP_DEBUG=false且日志不可写。
方法二：验证重写是否生效
故意访问一个绝对不存在的路径，例如 【http://你的域名/xyzabc123】：
→ 返回ThinkPHP自带的黄色404页（含调试信息）：说明请求已进框架，问题出在路由定义或缓存；
→ 返回Nginx/Apache原生404：重写规则完全失效，跳去第三步。
方法三：Nginx用户加一行调试
在 public/index.php 顶部插入 var_dump($_SERVER['PATH_INFO']); die();，再访问 【/index/index】。输出为空，证明 【fastcgi_param PATH_INFO $fastcgi_path_info; 这行被注释或缺失】，PATH_INFO根本没传进来。
第三步：定位是环境错还是代码错
① 先跑命令看路由是否注册：php think route:list
输出为空？说明路由文件根本没执行。常见原因：
— TP6/TP8路由必须写在项目根目录的 routes.php（不是 route/route.php）；
— 文件开头漏了 use think\facade\Route;；
— 多应用模式下，路由写在了 app/route/app.php 却该放在 app/index/route/app.php。
② 再查关键配置开关：
打开 config/app.php，确认这两项为 true：'url_route_on' => true（关了等于废掉整个路由系统）；'app_debug' => true（关闭后错误不显示也不记录，只剩白屏）。
③ 最后盯死vendor/autoload.php：
报 【Class 'think\App' not found】？本质是自动加载器失效。上传前必须执行 composer install --no-dev，不能直接复制本地vendor；检查 index.php 中引入路径是否硬编码了本地绝对路径（如 /Users/xxx/vendor/autoload.php），应改为 __DIR__ . '/../vendor/autoload.php'。
第四步：专治升级后特有的坑
TP5升TP6必踩的雷：
— 不是 composer update 能解决的，必须新建TP6项目再迁移；
— 原TP5的 application/ 目录在TP6中彻底废弃，控制器得按PSR-4规范放进 app/controller/；
— 数据库查询语法断裂：Db::table('user')->whereTime() 在TP6里直接报错，必须先 composer require topthink/think-helper，再 use think\helper\Query; 才能用。
TP6升TP8.1注意：
TP8.1要求PHP ≥ 8.1，且新增枚举值校验功能——若旧代码用了自定义枚举类但没继承 think\enum\Enum，启动时就会Fatal error；
路由分类默认处理机制启用后，config/route.php 里的 default_route 配置可能被忽略，需检查是否误删了 route_config_file 的显式声明。
宝塔7.5.0+用户特别提示：
升级后TP5项目404，大概率是面板清掉了 fastcgi_split_path_info 和 fastcgi_param PATH_INFO 这两行。进网站配置文件，找到 location ~ \.php$ 区块，确保里面包含：fastcgi_split_path_info ^(.+\.php)(/.+)$;fastcgi_param PATH_INFO $fastcgi_path_info;
