独立安装 think-orm 3.0 必须先卸载 v2.x 版本，否则 db 类异常、query 方法缺失；db::name() 会加载模型配置但延迟报错，db::table() 更安全；buildsql() 仅调试用，不执行绑定；v3.0 空结果严格返回 null，需改用空安全操作符。
独立安装 think-orm 3.0 必须先卸载旧版
直接 composer require topthink/think-orm 在已有 TP6/TP8 项目中大概率失败，因为旧版 topthink/think-orm（v2.x）会与 v3.0 冲突，导致 Db 类行为异常、Query 实例方法缺失或返回 null 而不报错。
正确做法是：
- 先运行
composer remove topthink/think-orm，彻底清除旧依赖 - 确认
composer.json中"minimum-stability"为"stable"，避免拉取dev分支引发路由解析失败 - 再执行
composer require topthink/think-orm:^3.0 - 完成后检查
vendor/topthink/think-orm/src/Query.php是否存在——这是链式构造器的基类，缺了就说明没装对
Db::table() 和 Db::name() 返回值一样但语义不同
两者都返回 think\db\Query 实例，支持无限链式调用，但触发模型加载的时机和风险点完全不同。
Db::table('user') 是纯表名操作，不查模型文件，适合日志表、临时跨库查询；Db::name('user') 会尝试加载 app\model\User，仅读取其 $table、$pk 等配置，不执行构造函数——但如果模型类里有语法错误（比如用了 PHP 8.0 的联合类型但环境是 8.1），它会在 select() 时才暴露，而不是初始化时。
常见踩坑：
- 误以为
Db::name('user')一定比Db::table('user')“更安全”，其实前者反而更容易因模型定义问题导致静默失败 - 在模型不存在时，
Db::name('xxx')会退化为普通表处理，但若表名拼写错误（如Db::name('uers')），也不会报错，直到select()才抛 PDO 异常 - 所有链式方法（
where、order、limit）返回自身，但末尾方法（select、find、value）会立即执行并清空绑定参数——这意味着你不能在select()后再加->where()
buildSql() 只用于调试，不能拿去拼接执行
buildSql() 返回的是带问号占位符的原生 SQL 字符串，例如 SELECT * FROM `user` WHERE `status` = ?。它不含引号、不转义、不替换参数，纯粹供人工阅读或日志记录。
真实执行必须走 select() 或 find()，由 PDO 底层完成参数绑定。否则手动拼接字符串等于绕过防注入机制。
调试时建议组合使用：
-
$sql = $query->buildSql();查看结构 -
var_dump($query->getBind());查看当前已绑定的参数（注意：未显式bind()的值不会出现在这里） -
var_dump($query->getOptions('where'));查看原始条件数组，确认是否被意外覆盖或丢弃
别忘了：一旦调用了 select()，getBind() 就会清空，所以调试顺序必须是先 buildSql() + getBind()，再 select()。
升级后 ORM 返回 null 不再自动转 false
ThinkORM 3.0 对空结果严格返回 null，而不再是 TP6 的空集合或假值。这意味着 if ($user) 这种判空逻辑在 PHP 8.1+ 下会触发 TypeError，因为 $user->name 访问了 null。
必须改用空安全操作符：
- 把
if ($user && $user->name)改成if ($user?->name) - 把
return $user->toArray();改成return $user?->toArray() ?: []; - 模型主键类型也要显式声明：
protected $pkType = 'int';或'string'，否则关联预载入（load()）可能失效且无提示
最容易被忽略的是：即使你没改任何代码，只要启用了 declare(strict_types=1)（TP8 推荐做法），旧判空逻辑就会立刻崩掉——这不是 ORM 的 bug，而是 PHP 类型系统在帮你提前暴露隐患。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
