ThinkPHP版本升级注意事项-ThinkPHP-PHP中文网

thinkphp跨大版本升级需重点解决环境错配、缓存残留、类加载失效三大问题：确认cli与web sapi的php版本及扩展一致；用composer更新并清空runtime；重构目录结构、命名空间、配置加载方式；调整中间件、路由、db查询等关键逻辑。

thinkphp版本升级注意事项

ThinkPHP 跨大版本升级（比如 5→6、6→8）不是改个 composer.json 版本号就能跑通的事，绝大多数线上故障都出在环境错配、缓存残留或类加载失效这三处——尤其 PHP CLI 和 Web SAPI 版本不一致时，composer update 成功但浏览器直接 500。

很多“升级失败”其实卡在第一步：你以为的 PHP 版本，和框架实际运行的不是同一个。

用 php -v 查 CLI 版本，再用 phpinfo() 或 php -r "echo php_sapi_name();" 确认 Web SAPI（如 fpm-fcgi）用的也是 ≥8.0（TP8）或 ≥7.1（TP6）
检查 mbstring、openssl、pdo_mysql、json、fileinfo 是否全部启用：php -m | grep -E "mbstring|openssl|pdo|json|fileinfo"
Windows 下常漏掉 extension=php_fileinfo.dll（默认被注释），Docker 用户要确认基础镜像已安装 fileinfo 扩展，不只是改 php.ini
TP8 强制要求 php: ">=8.0.0" 写进 composer.json 的 require，否则 Composer 可能锁死旧依赖

手动下载 ZIP、拖进项目覆盖 thinkphp/ 目录是 TP3/5 时代的做法，TP6 起所有类靠 Composer PSR-4 自动加载，硬拷会导致 Class 'think\App' not found 这类致命错误。

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

只改 composer.json 中的 "topthink/framework": "^8.0"，然后运行 composer update topthink/framework --with-all-dependencies
如果提示依赖冲突，不要跳过，一并升级 monolog/monolog、psr/log 等子依赖
升级后必须删掉 runtime/ 目录——缓存残留会让路由、配置、模板引擎读取旧逻辑，现象是“代码改了但没生效”
执行 composer dump-autoload -o 后，立刻跑 php think clear 清空所有缓存

TP6 彻底废弃 application/ 目录，TP8 进一步收紧自动加载规则；老项目直接复制旧结构进去，90% 会 404 或类找不到。

application/ → 全部改为小写的 app/，控制器路径从 application/index/controller/Index.php 改为 app/controller/Index.php，命名空间对应改成 app\controller\Index
所有 use think\Controller 必须删掉或换成 use think\facade\View；use think\Model 改为 use think\Model as BaseModel 并继承它
config.php 单文件模式废弃，所有配置拆进 config/app.php、config/database.php 等；自定义配置如 config/api.php 不会自动加载，必须显式调用 Config::load('api.php', 'api')
.env 文件只对 env() 函数读取的字段生效，比如 config/database.php 里得写 'hostname' => env('DB_HOST', '127.0.0.1')，硬编码无效

这些地方改错不会立即报错，但请求进不来、中间件不执行、数据库查不到数据——问题难定位，容易误判为“框架 bug”。

中间件 handle() 方法签名必须加第三个参数：public function handle($request, Closure $next, $params = [])，缺了框架直接跳过
路由必须从 route/route.php 移到 app/Route.php，且字符串写法 Route::get('user', 'index/user/index') 已废弃，改用数组或闭包：Route::get('user', [\app\controller\Index::class, 'index'])
Db::name('user') 在 TP6+ 已移除，统一用 Db::table('user') 或模型操作；若用模型，记得新建 app/model/UserModel.php 并继承 BaseModel
Request::instance() 废弃，改用 think\facade\Request 或注入 think\Request；url() 助手函数默认不补模块名，建议统一走命名路由：Route::get('home', 'index/index')->name('home')，模板中用 {:url('@home')}