ThinkORM模型需继承think\orm\Model、严格遵循PSR-4规范、显式配置$table和$pk、绑定$connection连接、启用Timestamp与SoftDelete特性，否则将报错或功能失效。
如果您在 ThinkPHP 项目中尝试使用 ThinkORM（即 ThinkPHP 6.1+ 内置的全新 ORM，取代旧版 think\Model），但模型无法正常查询或报错“Class not found”“Table not found”等，则很可能是模型配置方式与旧版 think\Model 混淆所致。以下是 ThinkORM 模型的正确配置方法：
一、确认使用的是 ThinkORM 而非旧版 think\Model
ThinkORM 是 ThinkPHP 6.1 引入的独立 ORM 组件，其基类为 think\orm\Model，而非 think\Model。若仍 use think\Model，则实际加载的是已废弃的兼容层，将导致关联、动态属性、JSON 字段等特性失效。
1、检查模型文件顶部命名空间与 use 语句是否为：
namespace app\model;
use think\orm\Model;
2、确认 composer.json 中已安装 think-orm：运行 composer show topthink/think-orm 验证版本不低于 v3.0.0。
立即学习“PHP免费学习笔记（深入）”；
3、禁止在模型中继承 think\Model —— 此类写法会绕过 ThinkORM 的完整生命周期与查询构建器。
二、严格遵循 PSR-4 与目录结构规范
ThinkORM 依赖自动加载机制精准定位模型类，任何路径、命名空间或文件名偏差都将导致类无法实例化。框架不再容忍大小写松散或斜杠方向错误。
1、模型文件必须存放于 app/model/ 目录下（注意是小写 model，非 Model 或 MODEL）。
2、文件名必须与类名完全一致且首字母大写，例如类名为 User，则文件必须为 app/model/User.php，不可为 user.php 或 UserModel.php。
3、命名空间必须为 app\model（全小写），不可写作 App\Model、app\Model 或 app\model\UserModel。
4、类定义中不得省略 extends 声明，必须显式继承 think\orm\Model：
class User extends \think\orm\Model {}
三、显式配置数据表与主键（禁用自动推导）
ThinkORM 默认关闭表名自动推导（区别于旧版），必须通过 $table 属性或构造参数明确指定表名，否则将尝试访问与类名全小写同名的表（如 User → user），极易出错。
1、在模型类中声明 protected $table 属性：
protected $table = 'tp_user';
2、若需复用同一张表的多个模型（如 AdminUser 与 FrontUser 同属 tp_user 表），必须为每个模型单独设置 $table，不可依赖前缀移除或驼峰转换。
3、主键字段必须显式声明：
protected $pk = 'uid';
若主键非 id 且未设置，findAll()、find($id) 等方法将无法按主键定位。
四、启用数据库连接配置并绑定模型
ThinkORM 不读取 database.php 中的默认连接别名，而是通过 $connection 属性或全局 Db::connect() 显式指定连接配置键名。未绑定有效连接时，所有查询均抛出 ConnectionException。
1、确认 config/database.php 中已定义至少一个连接配置块，例如：
'mysql_admin' => [
'type' => 'mysql',
'hostname' => '127.0.0.1',
'database' => 'admin_db'
]
2、在模型中绑定该连接：
protected $connection = 'mysql_admin';
3、若使用多库且某模型需切换连接，禁止在控制器中调用 Db::connect()->name('User')，而应直接在模型内设置 $connection 属性，避免跨请求连接污染。
五、配置时间戳与软删除字段
ThinkORM 对 create_time/update_time/delete_time 字段的识别高度依赖显式声明，不支持隐式约定。未配置时，save() 不会自动写入时间，softDelete() 亦无法生效。
1、启用自动时间戳：
protected $autoWriteTimestamp = true;
2、指定创建与更新字段名：
protected $createTime = 'create_at';
protected $updateTime = 'update_at';
3、启用软删除并指定删除标记字段：
use think\orm\concern\SoftDelete;
use think\orm\concern\Timestamp;
class User extends Model {
use SoftDelete, Timestamp;
protected $deleteTime = 'delete_time';
protected $defaultSoftDelete = 0;
}
