ThinkPHP5升级到ThinkPHP6避坑指南_核心架构变更差异解析

从TP5迁移到TP6，你可能正踩在这些“坑”上

如果你正打算把ThinkPHP5的项目升级到ThinkPHP6，先停下来，深呼吸。很多人第一次接触TP6时，都会下意识地执行 composer update，然后发现整个项目直接炸了——这其实是意料之中的事。TP6不是TP5的小修小补，它是完全基于PHP 7.1+重写的新框架，命名空间、核心类、目录结构全是新的。

说句大白话：这根本不是升级，是“搬家”。而且你得全部家当打包好，一个零件一个零件地搬到新楼里，零兼容。硬上的后果是什么？Class 'think\App' not found 这种错误只是开胃菜，后面还有一连串莫名其妙的报错等着你。

Class 'think\App' not found？别慌，但得重头来

直接 composer update 或者 composer require topthink/framework:^6.0 都行不通——TP6根本不认TP5的命名空间和核心类。最有把握的方式是新建项目：

• 执行 composer create-project topthink/think tp6 拉一个干净的骨架项目
• 把旧项目 application/ 目录下的逻辑拆开，逐个迁入新目录 app/（注意，这个目录是按照PSR-4规范组织的，命名空间得严格对应，比如 app\controller\Index）
• 迁移完后，初次访问如果报 Class 'think\App' not found，说明还有代码在引用TP5的全局类，赶紧全局搜索替换掉

配置全失效？问题可能出在 .env 和 config/ 结构上

TP5时代，所有配置都堆在 config.php 一个文件里，方便是方便，但到了TP6，这个做法完全行不通了。配置被拆分成了 config/app.php、config/database.php 这样的模块化文件，而且优先级最高的是根目录下的 .env。

这里有个非常容易踩的坑：如果你没建 .env，或者里面写了 APP_DEBUG=false，那即使你在 app.php 里把 app_debug 设成了 true，调试模式也始终是关的——就是这么“霸道”。所以：

• .env 文件必须放在项目根目录，文件名就是 .env（没有后缀，没有空格），内容用 KEY=VALUE 格式
• 密码里如果包含 @、# 这类特殊字符，值必须用双引号包起来：DB_PASSWORD="p@ss#word!"
• config/database.php 里不能再写 mysql:// 这种连接字符串了，得改成数组：'hostname' => '127.0.0.1', 'database' => 'test'

路由参数拿不到？补上 merge_param 选项就行

TP5里，你用 input('id') 或 $request->param('id') 总能取到路由参数，因为框架默认把URL路径、GET、POST的参数全合并了。但TP6默认只合并query和post参数，路由变量不自动合并。

这就导致一个很尴尬的场景：你定义了一个 Route::get('user/:id', 'user/read')，迁移后发现 $id 始终为空。解决办法有两个：

• 路由定义时显式开启合并：Route::get('user/:id', [\app\controller\User::class, 'read'])->option(['merge_param' => true])
• 或者直接用资源路由：Route::resource('user', 'User');，它默认就启用了 merge_param
• 旧代码里依赖 input('id') 的地方，统一改成 $request->param('id')，并确认路由是否带上了合并选项

查询结果总是对象？别忘了 ->toArray()

TP6里，Db::select() 和模型的 find() / select() 返回的都是 Collection 对象，不再是数组。直接 foreach 循环可能没大问题，但如果你要 json_encode 输出到前端，结果很可能是个你意想不到的结构——前端收不到 data 字段就是典型的连锁反应。

所以：

• 显式转数组：Db::name('user')->select()->toArray() 或 $users->toArray()
• whereTime()、whereLike() 这类快捷方法已经从核心移到了扩展包里，需要安装：composer require topthink/think-helper，然后 use think\helper\Query;
• 模型的查询方法也变了：取消了 get()、all()、getOrFail()，统一用 find() 和 select()，且必须注意返回类型

还有一点特别容易被忽略：TP6默认不开启Session，也不自带模板引擎和多应用支持。如果你想用 fetch() 渲染模板，或者让 app/admin 的路由不返回404，就得手动安装 topthink/think-view 和 topthink/think-multi-app。这些不是锦上添花的功能，而是刚需。少了它们，项目基本跑不起来。